API Setup

Connect the Surface MCP server to your AI assistant. All connections require your Surface API key, which scopes every tool call to your environment.

Don't have an API key yet? Create one in Settings > API Keys in your Surface dashboard. The key is only shown once, so save it securely.

A new connection loads the default forms bundle (39 of 110 tools). To load a different set, add ?tools= to the server URL in any of the configs below, e.g. https://app.withsurface.com/mcp?tools=all. See Tool Bundles.

Claude Desktop

In Claude Desktop, go to Settings > Developer > Edit Config to open your claude_desktop_config.json.

Add the following to your config file, replacing <your-api-key> with your actual API key:

{
  "mcpServers": {
    "surface-forms": {
      "url": "https://app.withsurface.com/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Restart Claude Desktop and look for the MCP icon in the chat input to confirm the server is connected.

Cursor

Go to Cursor Settings > MCP and click Add new MCP server.

Type: HTTP
Name: surface-forms
URL: https://app.withsurface.com/mcp
Headers: Authorization: Bearer <your-api-key>

Claude Code

Run the following command in your terminal:

claude mcp add --transport http surface-forms https://app.withsurface.com/mcp \
  --header "Authorization: Bearer <your-api-key>"

Verify the server is configured:

claude mcp list

Windsurf

Go to Windsurf Settings > Cascade > Model Context Protocol (MCP) and click Add Server or edit your ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "surface-forms": {
      "serverUrl": "https://app.withsurface.com/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Refresh the MCP panel and check that surface-forms shows as connected.

Other Editors

Any editor that supports Streamable HTTP can connect to the Surface MCP server. Use this configuration:

{
  "mcpServers": {
    "surface-forms": {
      "url": "https://app.withsurface.com/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

The Surface MCP server uses the Streamable HTTP transport: no local process or Docker container required. Just point your client to the URL with your API key.

Read-only connections

API keys are full-access, so the connection can create, edit, and publish. To hand a key to an agent that should only read, add ?readonly=1 to the URL:

https://app.withsurface.com/mcp?readonly=1

This drops every write and admin tool from the connection, whatever the credential allows. It combines with ?tools=; see Tool Bundles.

Troubleshooting

›Server not connecting

Double-check that your API key is correct and hasn't been revoked.
Make sure the Authorization header uses the Bearer prefix.
Confirm your editor supports the Streamable HTTP transport.

›A tool I expected is missing

The default connection loads the forms bundle. Add ?tools=all (or the bundle or family you need) to the server URL.
On a ?readonly=1 connection, write tools are deliberately absent.
Note for ?tools=: a selection containing a typo falls back to the full surface rather than silently narrowing it.

›Tools not returning data

Your API key is scoped to a specific environment. Make sure the environment has forms, responses, or leads to query.
Form edits save a draft. Visitors only see them after publish_form promotes the draft to live.

›Rate limiting or timeouts

The MCP server is hosted on the same infrastructure as the Surface app. If you're experiencing timeouts, try again in a moment.
For large datasets, use pagination parameters (page, limit) to fetch data in smaller chunks.