# Tool Bundles The Surface MCP server exposes 128 tools. Loading every definition at once fills up an assistant's context, so a connection that asks for nothing specific gets the **forms and vault bundles**: the core form-building tools plus responses, AI scores, and the environment's knowledge Vault. To load anything else, name a bundle, a tool family, or an exact list of tool names. ## Bundles [#bundles] A bundle is a set of tool families for one kind of session: | Bundle | Focus | Families | Tools | | ---------- | ----------------------------------------------------------- | -------------------------------------------------- | ----- | | `forms` | Building forms and reading their results (in the default) | forms, responses, scoring | 41 | | `vault` | The environment's Markdown knowledge Vault (in the default) | vault | 4 | | `content` | CMS, blogs, content analytics, AI visibility | cms, contentReview, contentAnalytics, aiVisibility | 55 | | `insights` | Responses, leads, analytics, scores, workflow runs | analytics, scoring, leads, responses, workflows | 20 | | `admin` | Team, members, environments, feedback | team, members, environments, feedback | 4 | | `all` | Everything | all 16 families | 128 | An unconfigured connection combines the `forms` and `vault` bundles (45 tools). ## Families [#families] Families are the smaller unit inside a bundle. You can select any of them directly: | Family | What it covers | Tools | | ------------------ | ----------------------------------------------------------------------------------------------------------- | ----- | | `forms` | Create, edit, style, route, and publish forms, including SDK form authoring (binding maps, HTML validation) | 33 | | `responses` | Read form submissions | 2 | | `leads` | Qualified leads and lead counts, lead import | 3 | | `analytics` | Form, funnel, landing page, and environment analytics | 7 | | `workflows` | Workflow run logs and per-step details | 2 | | `scoring` | AI lead scores, response search, form comparisons | 6 | | `vault` | The environment's Markdown knowledge Vault | 4 | | `hubspot` | Read connected HubSpot contacts, companies, deals, owners, and properties | 12 | | `cms` | Headless CMS content types, entries, and assets | 25 | | `contentReview` | The blog review pipeline | 12 | | `contentAnalytics` | Content performance and AI traffic sources | 7 | | `aiVisibility` | AEO/GEO answer-engine visibility reports, prompts, and scans | 11 | | `team` | Team, subscription, and billing info | 1 | | `members` | Member invitations | 1 | | `environments` | Environment creation | 1 | | `feedback` | Product feedback to the Surface team | 1 | ## Choosing What Loads [#choosing-what-loads] Selection goes on the `?tools=` query parameter of the one `/mcp` endpoint, so it works in every client that accepts a URL. The value is a comma-separated list of bundles, family names, and individual tool names: ``` https://app.withsurface.com/mcp default forms + vault bundles https://app.withsurface.com/mcp?tools=all full surface https://app.withsurface.com/mcp?tools=content one bundle https://app.withsurface.com/mcp?tools=responses,leads families https://app.withsurface.com/mcp?tools=forms,cms bundle + family https://app.withsurface.com/mcp?tools=list_forms,get_form_analytics individual tools ``` Three rules: * `forms` names the bundle, not the bare family, so `?tools=forms` also carries the responses and scoring tools. * A selection containing any unknown name falls back to everything, so a typo cannot produce a zero-tool server or silently narrow the set. * A known tool name your connection's credential excludes (a write tool on a read-only connection) is skipped, not treated as a typo. ### Header Alternative [#header-alternative] For clients that configure headers but not URLs, the `X-Surface-Tool-Families` header takes the same comma-separated list. `?tools=` wins when both are present: ```json { "headers": { "Authorization": "Bearer ", "X-Surface-Tool-Families": "content" } } ``` ### Per-client Recipes [#per-client-recipes] Claude Code Cursor Claude Desktop ```sh # The default forms + vault bundles need no selection claude mcp add --transport http surface-forms "https://app.withsurface.com/mcp" \ --header "Authorization: Bearer " # An insights session claude mcp add --transport http surface-insights "https://app.withsurface.com/mcp?tools=insights" \ --header "Authorization: Bearer " ``` ```json // .cursor/mcp.json: an insights session { "mcpServers": { "surface-forms": { "url": "https://app.withsurface.com/mcp?tools=insights", "headers": { "Authorization": "Bearer " } } } } ``` ```json // claude_desktop_config.json: everything { "mcpServers": { "surface-forms": { "url": "https://app.withsurface.com/mcp?tools=all", "headers": { "Authorization": "Bearer " } } } } ``` ## Read-only Connections [#read-only-connections] Add `?readonly=1` to get a connection with no write or admin tools, whatever the credential can otherwise do. It combines with `?tools=`: ``` https://app.withsurface.com/mcp?readonly=1 reads of the default bundles https://app.withsurface.com/mcp?tools=all&readonly=1 every read tool https://app.withsurface.com/mcp?tools=content&readonly=1 content reads only ``` API keys are full-access by design, so `?readonly=1` is how you hand a key to an agent that should only read. OAuth connections without the write scope get the same read-only set either way. CMS tools are included: a read-only connection cannot see `cms_delete_entry` or any other CMS write. Whatever you select, every tool call stays scoped to the environment your API key or OAuth connection belongs to. Tool selection changes which definitions your assistant loads, never what it is allowed to touch.