MCP Adapter

The @codespar/mcp adapter exposes CodeSpar tools as an MCP (Model Context Protocol) server, allowing you to use them in Claude Desktop, Cursor, Windsurf, and any other MCP-compatible client. No code required -- configure the MCP server, restart your client, and the 6 meta-tools appear in the tool palette.

This is the fastest way to try CodeSpar. If you already use Claude Desktop or Cursor, you can be up and running in under 2 minutes.

Installation

npm install -g @codespar/mcp

pnpm add -g @codespar/mcp

yarn global add @codespar/mcp

[!TIP] You do not need to install globally. The MCP configuration below uses npx, which will download and run @codespar/mcp automatically. Global installation is only needed if you want to avoid the npx startup delay.

API Reference

getMcpConfig(options): McpConfig

Returns a generic MCP server configuration object that can be used with any MCP-compatible client. This is the base function -- the client-specific helpers below call it internally.

import { getMcpConfig } from "@codespar/mcp";

const config = getMcpConfig({
  apiKey: process.env.CODESPAR_API_KEY,
  servers: ["stripe", "mercadopago", "correios"],
});

console.log(JSON.stringify(config, null, 2));

{
  "command": "npx",
  "args": ["@codespar/mcp", "serve", "--servers", "stripe,mercadopago,correios"],
  "env": {
    "CODESPAR_API_KEY": "csk_live_..."
  }
}

Parameters:

getClaudeDesktopConfig(options): ClaudeDesktopConfig

Returns a configuration snippet ready to paste into Claude Desktop's claude_desktop_config.json. The output is the complete mcpServers block.

import { getClaudeDesktopConfig } from "@codespar/mcp";

const config = getClaudeDesktopConfig({
  apiKey: "csk_live_your_key_here",
  servers: ["stripe", "asaas", "correios", "twilio"],
});

console.log(JSON.stringify(config, null, 2));

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "stripe,asaas,correios,twilio"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

getCursorConfig(options): CursorConfig

Returns a configuration snippet for Cursor's MCP settings file (.cursor/mcp.json).

import { getCursorConfig } from "@codespar/mcp";

const config = getCursorConfig({
  apiKey: "csk_live_your_key_here",
  servers: ["stripe", "twilio"],
});

console.log(JSON.stringify(config, null, 2));

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "stripe,twilio"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

Setup guides

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "stripe,mercadopago,correios"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "codespar": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

import { getMcpConfig } from "@codespar/mcp";

const config = getMcpConfig({
  apiKey: process.env.CODESPAR_API_KEY,
  servers: ["stripe", "mercadopago", "correios", "twilio"],
});

// Pass this config to your MCP client implementation
// The MCP server will spawn as a child process using the command and args

{
  "tools": [
    {
      "name": "codespar_discover",
      "description": "Find available commerce tools by domain",
      "inputSchema": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "enum": ["payments", "fiscal", "logistics", "messaging", "banking", "erp", "crypto"]
          }
        },
        "required": ["domain"]
      }
    },
    {
      "name": "codespar_checkout",
      "description": "Create a checkout session for a product or service",
      "inputSchema": {
        "type": "object",
        "properties": {
          "provider": { "type": "string" },
          "amount": { "type": "number" },
          "currency": { "type": "string" },
          "description": { "type": "string" },
          "payment_methods": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["provider", "amount", "currency"]
      }
    }
  ]
}

Specifying servers

By default, the MCP adapter connects to all available servers. You can limit which servers are accessible using the --servers flag. This is useful for scoping the tool set to a specific domain:

{
  "mcpServers": {
    "codespar-payments": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "stripe,mercadopago,asaas"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

You can also run multiple CodeSpar MCP servers with different scopes:

{
  "mcpServers": {
    "codespar-payments": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "stripe,mercadopago"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    },
    "codespar-logistics": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve", "--servers", "correios,jadlog,melhorenvio"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

[!TIP] Scoping servers improves tool selection accuracy. When the model has fewer tools to choose from, it makes better decisions about which one to call.

Using sandbox keys

For testing, use a csk_test_ API key. The MCP server will route all tool calls to sandbox servers that return realistic mock data:

{
  "mcpServers": {
    "codespar-sandbox": {
      "command": "npx",
      "args": ["@codespar/mcp", "serve"],
      "env": {
        "CODESPAR_API_KEY": "csk_test_your_key_here"
      }
    }
  }
}

[!NOTE] Sandbox and production share the same tool interface. Switching from test to live is a single environment variable change.

Troubleshooting

Tools do not appear after restart

1. Verify the config file location. Claude Desktop looks for claude_desktop_config.json in:

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

2. Validate JSON syntax. A missing comma or bracket will silently fail. Use cat claude_desktop_config.json | python3 -m json.tool to validate.

3. Check that npx is available. Open a terminal and run npx --version. If it is not installed, install Node.js 18+.

4. Check the API key. Ensure it starts with csk_live_ or csk_test_. Keys are case-sensitive.

MCP server crashes on startup

Check the MCP server logs:

• Claude Desktop: Open the developer console (Cmd+Option+I on macOS) and look for MCP-related errors.
• Cursor: Check the Output panel (Cmd+Shift+U) and select "MCP" from the dropdown.

Common causes:

Tool calls return errors

If the MCP server is running but tool calls fail:

1. Check server availability. Not all 57 servers are available in all regions. Use codespar_discover to see which servers are active for your account.
2. Verify parameters. Tool call errors often come from missing required parameters. Check the tool's inputSchema for required fields.
3. Check rate limits. Sandbox keys have lower rate limits than production keys.

Slow startup

The first run with npx downloads the @codespar/mcp package, which takes a few seconds. Subsequent runs use the cached version. To eliminate this delay, install globally:

npm install -g @codespar/mcp

Then update the config to use the global binary:

{
  "mcpServers": {
    "codespar": {
      "command": "codespar-mcp",
      "args": ["serve"],
      "env": {
        "CODESPAR_API_KEY": "csk_live_your_key_here"
      }
    }
  }
}

Next steps

• Introduction -- Architecture overview and the Complete Loop
• Sessions -- How sessions and servers work under the hood
• Tools and Meta-Tools -- The 6 meta-tools explained in detail
• Claude Adapter -- Programmatic integration with the Anthropic SDK
• OpenAI Adapter -- Programmatic integration with the OpenAI SDK
• Quickstart -- End-to-end setup for programmatic usage