Skip to main content

Client Setup

This guide covers how to configure popular AI clients to connect to the Spotto MCP server. Choose your client below for specific setup instructions.

Before You Begin

Make sure you've completed the Getting Started guide to generate an API key and identify your regional endpoint.

Claude Code CLI​

Claude Code is Anthropic's command-line interface for Claude. Adding an MCP server is straightforward:

claude mcp add spotto --transport http https://mcp-au.spotto.ai/mcp --header "X-API-Key: YOUR_API_KEY"

Replace YOUR_API_KEY with your Spotto API key and adjust the endpoint URL for your region.

To verify the connection:

claude mcp list

You should see spotto listed with its available tools.

Environment Variables​

For better security, you can use an environment variable instead of hardcoding your API key:

export SPOTTO_API_KEY="your_api_key_here"
claude mcp add spotto --transport http https://mcp-au.spotto.ai/mcp --header "X-API-Key: $SPOTTO_API_KEY"

Claude Desktop​

Claude Desktop stores MCP configuration in a JSON file. The location depends on your operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Create or edit this file with the following content:

{
  "mcpServers": {
    "spotto": {
      "transport": "http",
      "url": "https://mcp-au.spotto.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

After saving the file, restart Claude Desktop for the changes to take effect.

Adding Multiple Servers​

If you already have other MCP servers configured, add Spotto to the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": {
      ...
    },
    "spotto": {
      "transport": "http",
      "url": "https://mcp-au.spotto.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Cursor​

Cursor supports MCP through its settings file. You can configure it at the project level or globally:

  • Project-level: .cursor/mcp.json in your project root
  • Global: Check Cursor's documentation for the global settings location
{
  "mcpServers": {
    "spotto": {
      "transport": "http",
      "url": "https://mcp-au.spotto.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Restart Cursor after saving the configuration.

Windsurf​

Windsurf (by Codeium) uses a similar configuration format. Add Spotto to your MCP settings:

{
  "mcpServers": {
    "spotto": {
      "serverUrl": "https://mcp-au.spotto.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Note that Windsurf uses serverUrl instead of url.

OpenAI Codex CLI​

For OpenAI's Codex CLI, add the configuration to your codex.toml or ~/.codex/config.toml. The rmcp client requires specific configuration keys for headers:

Option 1: Static Headers (Direct Value)​

Use this when you want to put the API key directly in the config file:

[mcp_servers.spotto]
url = "https://mcp-au.spotto.ai/mcp"
http_headers = { "X-API-Key" = "YOUR_API_KEY" }

Option 2: Environment Variable Headers (Secure)​

Use this to reference an environment variable for better security:

[mcp_servers.spotto]
url = "https://mcp-au.spotto.ai/mcp"
env_http_headers = { "X-API-Key" = "SPOTTO_API_KEY" }

Then set the environment variable:

export SPOTTO_API_KEY="your_api_key_here"

Generic HTTP Client​

For any MCP-compatible client using HTTP transport, configure it with these settings:

SettingValue
URLhttps://mcp-au.spotto.ai/mcp (or your regional endpoint)
MethodPOST
Content-Typeapplication/json
AuthenticationX-API-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY

The server accepts both authentication methods—use whichever your client supports.

Request Format​

MCP uses JSON-RPC 2.0. A typical request looks like:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get-api-status",
    "arguments": {}
  },
  "id": 1
}

Verifying Your Setup​

After configuring your client, test the connection by asking a simple question:

"What companies do I have access to in Spotto?"

or

"Check the Spotto API status"

If the AI assistant returns information about your Spotto account, the integration is working correctly.

Regional Endpoints Reference​

RegionEndpoint
Australiahttps://mcp-au.spotto.ai/mcp
United Stateshttps://mcp-us.spotto.ai/mcp
Europehttps://mcp-eu.spotto.ai/mcp

Troubleshooting​

Client doesn't recognize the Spotto tools​

  • Restart your AI client after updating the configuration
  • Verify the JSON syntax in your configuration file
  • Check that the URL and API key are correct

"Invalid API key" errors​

  • Confirm you're using the full API key (starts with apik_)
  • Verify the key hasn't been revoked in the Spotto Portal
  • Check you're using the correct regional endpoint for your account

Connection timeouts​

  • Ensure your network allows outbound HTTPS connections
  • Check if a firewall or proxy is blocking the connection
  • Try the curl test from the Getting Started guide

Next Steps​