Skip to main content

Getting Started: Spotto MCP Setup and API Key

Overview​

This guide walks you through connecting the Spotto MCP server to your AI client.

Prerequisites​

Before you begin, ensure you have:

  • A Spotto account with at least one connected Azure subscription
  • Access to the Spotto Portal
  • An MCP-compatible AI client installed (Claude Code, Cursor, Windsurf, etc.)

Step 1: Get Your API Key​

You'll need a Spotto API key to authenticate MCP requests. If you don't have one yet, follow the API Authentication guide to generate a key.

When creating your key, consider naming it something descriptive like "Claude Code MCP" or "Cursor Integration" so you can identify it later.

Step 2: Choose Your Region and Endpoint Profile​

First, select the MCP region that matches your Spotto account:

RegionDefault full endpoint
Australiahttps://mcp-au.spotto.ai/mcp
United Stateshttps://mcp-us.spotto.ai/mcp
Europehttps://mcp-eu.spotto.ai/mcp

Not sure which region you're in? Check the URL when you log into the Spotto Portal—it includes your region code (e.g., portal-au.spotto.ai).

Then choose the endpoint profile that fits your client:

ProfileUse it when
fullYou want both read and write tools in one MCP server
readYou mostly query data, or the client struggles to load the full tool catalog
writeYou want action tools only

For the regional -read and -write URLs, see MCP Endpoint Profiles.

Copilot-compatible fallback

If you're setting up GitHub Copilot, Copilot Studio, or Microsoft 365 Copilot and the client cannot retrieve the full Spotto tool list, use the matching regional read endpoint first.

Step 3: Test Connectivity​

Before configuring your AI client, you can verify the MCP server is reachable using curl:

curl -X POST https://mcp-au.spotto.ai/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Replace YOUR_API_KEY with your actual API key and adjust the endpoint for your region and profile. For example, switch to https://mcp-au-read.spotto.ai/mcp if you are testing the Australian read profile.

A successful response returns a JSON object listing available tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {"name": "get-api-status", "description": "Check API health and connectivity"},
      {"name": "get-current-user", "description": "Get your user profile and permissions"},
      ...
    ]
  }
}

If you receive an authentication error, double-check your API key and ensure it hasn't been revoked.

Step 4: Configure Your Client​

Now you're ready to set up your AI client. Head to the Client Setup guide for specific instructions for:

  • Claude Code CLI
  • Claude Desktop
  • Cursor
  • Microsoft Copilot Studio and Microsoft 365 Copilot
  • GitHub Copilot (VS Code)
  • Windsurf
  • OpenAI Codex CLI
  • Generic HTTP clients

Troubleshooting​

"Authentication failed" or 401 errors​

  • Verify your API key is correct and hasn't been revoked
  • Check that you're using the correct regional endpoint
  • If IP allowlisting is enabled, ensure your current IP is in the allowlist

See the API Authentication troubleshooting section for more details.

"Connection refused" or timeout errors​

  • Confirm you have internet connectivity
  • Check if your network blocks outbound HTTPS traffic
  • Try the curl test above to isolate whether it's a client or server issue

"No tools available" in your AI client​

  • Some clients cache the tool list—try restarting the client
  • Verify the MCP server configuration is correct in your client settings
  • If the client still cannot load the Spotto tool list, switch to the regional read endpoint
  • Run the curl test to confirm the server returns tools

"Limiting number of tool calls to 70" or "couldn't retrieve the requested items"​

  • This usually means the client cannot consume the full Spotto catalog from the default endpoint
  • Change the MCP URL to the matching regional read endpoint
  • Restart the client and test again with a simple read prompt
  • If you later need action tools, switch that workflow to the matching write endpoint

Next Steps​