API Setup

Connect the Surface Forms MCP server to your AI assistant. All connections require your Surface Forms 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 — save it securely.

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 Forms MCP server. Use this configuration:

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

The Surface Forms 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.

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.

›Tools not returning data

Your API key is scoped to a specific environment. Make sure the environment has forms, responses, or leads to query.
All tools are read-only — there are no tools that create or modify data.

›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.