Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.withsurface.com/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Open MCP config

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

Add the server

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>" }
    }
  }
}
3

Verify connection

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

​
Cursor

1

Open MCP settings

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

Configure the 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

1

Open MCP config

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

Add the server

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

Verify connection

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

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