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

A bundle is a set of tool families for one kind of session:

An unconfigured connection combines the forms and vault bundles (45 tools).

Families

Families are the smaller unit inside a bundle. You can select any of them directly:

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

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:

{
  "headers": {
    "Authorization": "Bearer <your-api-key>",
    "X-Surface-Tool-Families": "content"
  }
}

Per-client Recipes

# The default forms + vault bundles need no selection
claude mcp add --transport http surface-forms "https://app.withsurface.com/mcp" \
  --header "Authorization: Bearer <your-api-key>"

# An insights session
claude mcp add --transport http surface-insights "https://app.withsurface.com/mcp?tools=insights" \
  --header "Authorization: Bearer <your-api-key>"

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.