Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Claude Desktop installed (Download)
  • An Affonso API key from your dashboard
  • Claude Desktop version 0.7.0 or later (for Streamable HTTP support)

​
Configuration

​
Step 1: Locate the Config File

The Claude Desktop configuration file location depends on your operating system: 
~/Library/Application Support/Claude/claude_desktop_config.json

​
Step 2: Add Affonso MCP Server

Open the config file and add the Affonso MCP server configuration:
claude_desktop_config.json
{
  "mcpServers": {
    "affonso": {
      "url": "https://api.affonso.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key_here"
      },
      "transport": "streamable-http"
    }
  }
}
Replace sk_live_your_api_key_here with your actual API key from the Affonso dashboard.

​
Step 3: Restart Claude Desktop

After saving the configuration file, restart Claude Desktop to load the MCP server.

​
Verify Connection

Once Claude Desktop restarts, you should see the Affonso tools available. Try asking: 
What Affonso tools are available?
Or test with a simple query: 
List my affiliates

​
Local Development

For testing against a local Affonso API instance:
claude_desktop_config.json
{
  "mcpServers": {
    "affonso-local": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer sk_dev_your_dev_api_key"
      },
      "transport": "streamable-http"
    }
  }
}

​
Multiple Environments

You can configure multiple Affonso environments:
claude_desktop_config.json
{
  "mcpServers": {
    "affonso-prod": {
      "url": "https://api.affonso.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_production_key"
      },
      "transport": "streamable-http"
    },
    "affonso-staging": {
      "url": "https://staging-api.affonso.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_staging_key"
      },
      "transport": "streamable-http"
    }
  }
}

​
Troubleshooting

  1. Verify your API key is correct
  2. Check that the config file is valid JSON
  3. Restart Claude Desktop completely (quit and reopen)
  4. Check Claude Desktop logs for errors
  1. Ensure your API key starts with sk_live_ or sk_dev_
  2. Verify the key is active in your Affonso dashboard
  3. Check that the key has the required permissions
  1. Check your internet connection
  2. Verify https://api.affonso.io is accessible
  3. Check if a firewall is blocking the connection
  1. Wait a moment before retrying
  2. Check your plan’s rate limits
  3. Consider upgrading for higher limits

​
Security Best Practices

  • Use separate API keys for different environments
  • Rotate your API keys periodically
  • Use keys with minimal required permissions
  • Never share your configuration file

​
Next Steps

Explore Tools

See all available MCP tools

Example Queries

Learn what you can ask Claude