Tool Bundles

The Surface MCP server exposes 110 tools. Loading every definition upfront is real context pressure for an AI assistant, so a connection that doesn't ask for anything specific gets the forms bundle: the core form-building surface plus its responses and AI scores. Everything else is one config change away, as a curated bundle, a tool family, or an exact list of tool names.

Bundles

Bundles are curated sets of tool families for a kind of session:

Families

Families are the finer-grained unit underneath bundles. You can select any of them directly:

Choosing what loads

Selection rides the ?tools= query parameter on the one /mcp endpoint, so it works in every client that accepts a URL. The value is a comma-separated list mixing bundles, family names, and individual tool names:

https://app.withsurface.com/mcp                                       default forms bundle
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

A few rules worth knowing:

• 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 surface.
• 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 bundle needs 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 forms bundle
https://app.withsurface.com/mcp?tools=all&readonly=1        every read tool (59 of the 110)
https://app.withsurface.com/mcp?tools=content&readonly=1    content reads only

API keys are full-access by design, so ?readonly=1 is the way to hand a key to an agent that should only read. OAuth connections without the write scope get the same read-only surface either way. This covers CMS tools too: a read-only connection cannot see cms_delete_entry or any other CMS write.