Integration Guide

This guide walks you through setting up Kintsugi MCP in your development environment. Once configured, your AI coding assistant can search Kintsugi's docs and the live OpenAPI spec directly, so it writes integration code against the current API instead of a stale copy of the reference.

Prerequisites

Choose an MCP-capable AI coding assistant:

• Cursor IDE (recommended - built-in MCP support)
• Claude Desktop (for general API help)
• VS Code (through GitHub Copilot Chat's agent mode, or another MCP-capable extension)

Cursor IDE Setup

Cursor has built-in MCP support. Configuration is a JSON file — there's no wizard.

{
  "mcpServers": {
    "kintsugi": {
      "url": "https://docs.trykintsugi.com/mcp",
      "headers": {
        "X-API-KEY": "your-api-key",
        "X-ORGANIZATION-ID": "your-org-id"
      }
    }
  }
}

Using Kintsugi MCP in Cursor

Once configured, here's how to use it:

Claude Desktop Setup

Claude Desktop supports remote MCP servers from the config file below. If you're on an older version of Claude Desktop, you may need to run claude mcp add from the CLI or wrap the server with the mcp-remote proxy instead.

{
  "mcpServers": {
    "kintsugi": {
      "url": "https://docs.trykintsugi.com/mcp",
      "headers": {
        "X-API-KEY": "your-api-key",
        "X-ORGANIZATION-ID": "your-org-id"
      }
    }
  }
}

VS Code Setup

VS Code has built-in MCP support through GitHub Copilot Chat (agent mode). If you use a different chat extension with MCP support, the same JSON works.

{
  "servers": {
    "kintsugi": {
      "type": "http",
      "url": "https://docs.trykintsugi.com/mcp",
      "headers": {
        "X-API-KEY": "your-api-key",
        "X-ORGANIZATION-ID": "your-org-id"
      }
    }
  }
}

Custom MCP Client Setup

For advanced use cases, you can build your own MCP client on top of the official SDK.

Basic MCP Client Example

The Kintsugi MCP server speaks Streamable HTTP and exposes one tool per Customer API operation, named after its reference page (create-transaction, get-transactions, and so on). Each tool calls the API with the key you send in the connection headers.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('https://docs.trykintsugi.com/mcp'),
  {
    requestInit: {
      headers: {
        'X-API-KEY': process.env.KINTSUGI_API_KEY,
        'X-ORGANIZATION-ID': process.env.KINTSUGI_ORGANIZATION_ID,
      },
    },
  }
);

const client = new Client({
  name: 'kintsugi-dev-tool',
  version: '1.0.0',
});

await client.connect(transport);

// Discover what the server exposes
const { tools } = await client.listTools();
console.log('Tools:', tools.map((t) => t.name));
// -> ['search_kintsugi', 'query_docs_filesystem_kintsugi']

// Search the docs (returns matching pages with links and excerpts)
const result = await client.callTool({
  name: 'search_kintsugi',
  arguments: { query: 'POST /v1/tax/estimate request schema' },
});
console.log(result);

Integrating into Development Tools

You can build on Kintsugi MCP to power:

• Code generators - Pull the current spec at build time and regenerate clients
• API testing tools - Auto-generate test cases from the docs
• Documentation generators - Mirror the API reference into internal docs
• Custom IDE plugins - Build specialized tools for your team

Verification and Testing

After setup, verify your MCP integration works correctly.

Test 1: Endpoint discovery

Ask your AI: "What Kintsugi endpoints are available for tax calculation?"

Expected: The assistant lists relevant endpoints like /v1/tax/estimate and cites the docs page it found them on.

Test 2: Code generation

Ask your AI: "Generate Python code to call Kintsugi's tax estimation endpoint"

Expected: Working code with:

• The correct endpoint URL
• Both x-api-key and x-organization-id headers
• Payload fields that match the current schema

Test 3: Schema understanding

Ask your AI: "What's the request schema for creating a transaction in Kintsugi?"

Expected: A field-by-field breakdown pulled from the current OpenAPI spec — required vs. optional, field types, and any enum values.

Test 4: Debugging help

Show code with an error: "Why isn't this working?" (code that's missing required fields)

Expected: The assistant pulls the current schema via MCP and points out the specific fields that are missing or wrong.

Best Practices

Troubleshooting

Next Steps