MCP Adapter

@codespar/mcp is the CodeSpar MCP server as a local process. It speaks stdio to the client that spawns it (Claude Desktop, Cursor, Windsurf, Claude Code, any MCP host) and proxies every call to the same runtime that serves the hosted server: the same 15 meta-tools, the same policy engine, mandate check and audit chain. Only the transport differs.

Installation

npm install -g @codespar/mcp

pnpm add -g @codespar/mcp

yarn global add @codespar/mcp

You do not need to install globally. The configuration below uses npx, which downloads and runs @codespar/mcp on first use. A global install only removes the npx startup delay.

The one config block

Every stdio host takes the same object; only the file it lives in changes.

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

csk_test_ keys reach the test environment, csk_live_ keys reach production; the key prefix picks the environment and the server is otherwise identical. Keep a project-scoped file with a key in it out of git, or reference an environment variable from your shell profile.

First run and codespar_get_started

You do not need a valid API key just to boot the server. If CODESPAR_API_KEY is missing or invalid, the server starts in a guided setup mode instead of crashing: it stays connected to the client and exposes a single tool, codespar_get_started, that walks the agent through minting a key and validating the connection.

In setup mode the agent can:

1. Call codespar_get_started to learn why the full tool palette is not loaded (no key, or a key that failed validation).
2. Follow the returned steps to mint a key at Dashboard → API Keys.
3. Re-validate: once a working csk_ key is in place and the server restarts, the full meta-tool palette replaces the setup tool.

This means a fresh npx @codespar/mcp serve always produces a usable server; the agent itself can guide the user through the remaining setup instead of surfacing a startup crash. The hosted server does not have a setup mode: without a valid key it answers 401.

API Reference

The package also exports helpers that build the config block for you, for scripts that provision a developer machine or a CI runner.

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

Specifying servers

By default the server connects to all available providers. The --servers flag limits which ones the meta-tools may route to, which is useful for scoping the tool set to a 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"
      }
    }
  }
}

Test and live keys

A csk_test_ key puts the server in the test environment: the sandbox rails for Pix in, Pix out and the wallet ship pre-connected, no real money moves, and provider-backed tools dispatch against the fixtures you declare. Test mode is the reference. Test and live share the same tool interface, so moving to production is a single environment variable change:

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

Troubleshooting

Tools do not appear after restart

1. Verify the config file location. The table under The one config block lists the path per host.
2. Validate JSON syntax. A missing comma or bracket fails silently. Use python3 -m json.tool < claude_desktop_config.json 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. It starts with csk_live_ or csk_test_. Keys are case-sensitive, and a key must match the environment of its project.

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 server is running but tool calls fail:

1. Check what is connected. Not every provider is connected for every account. codespar_manage_connections lists what is, and codespar_discover recommends the tool for a use case.
2. Verify parameters. Tool call errors often come from missing required parameters. Each tool page carries the argument table generated from the published schema.
3. Check rate limits. Test keys have lower rate limits than production keys.

Slow startup

The first run with npx downloads the package, which takes a few seconds. Subsequent runs use the cached version. To eliminate the delay, install globally and point the config at the binary:

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

Next steps