Skip to main content

MCP Endpoint

Komashi exposes a Model Context Protocol (MCP) endpoint so AI clients and agents can work with your Komashi data directly — reading services, customers, subscriptions and invoices, and performing the actions your token permits — without you writing an API client first.

MCP is an alternative front end to the same platform. It does not add capabilities beyond what the REST API already exposes, and it is bound by the same token permissions.

Endpoint URL​

The endpoint is served from your own Komashi instance:

https://<your-instance>/mcp/komashiV1

Replace <your-instance> with the host of your Control Center. You can also copy the exact URL from Settings → API / MCP in the Control Center, where it is shown as Endpoint URL. See API Tokens.

Authentication​

The endpoint uses Bearer token authentication with a provider API token — the same token type you create in Settings → API / MCP:

Authorization: Bearer YOUR_API_KEY

Requests without a valid token are rejected with 401 Unauthenticated.

The token's Create / Read / Update / Delete permissions apply to MCP exactly as they do to the REST API. An AI client can never do more than the token allows, so scope the token to what the integration actually needs.

caution

An MCP client acts with your token's full authority. Issue a separate, minimally scoped token for each AI client rather than reusing your main integration token, and revoke it in Settings → API / MCP when you stop using it.

Transport​

The endpoint speaks JSON-RPC over HTTP:

  • Only POST is accepted. A GET returns 405 Method Not Allowed — there is no long-lived GET event stream to open.
  • Send Content-Type: application/json.
  • Responses are returned as JSON.

Most MCP clients handle this for you once you give them the URL and the token.

Connecting a client​

MCP clients differ in their configuration format, but they all need the same three things:

  1. The endpoint URL above.
  2. The Bearer token from Settings → API / MCP.
  3. HTTP (streamable) transport — not stdio, and not an SSE stream.

A typical client configuration entry looks like this:

{
  "mcpServers": {
    "komashi": {
      "type": "http",
      "url": "https://<your-instance>/mcp/komashiV1",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Once connected, the client discovers the available tools from the endpoint itself — that list is authoritative and reflects your token's permissions, so check it there rather than relying on a list copied into documentation.

Troubleshooting​

SymptomCause
401 UnauthenticatedMissing, expired, or revoked token. Check the Authorization header and the key list in Settings → API / MCP.
405 Method Not AllowedThe client sent a GET. Configure it for HTTP POST / streamable transport rather than SSE.
A tool is missing or an action failsThe token lacks the required permission. Update the key's permissions with the gear icon in Settings → API / MCP.
429Rate limit reached. The same per-key rate limits as the REST API apply — back off and retry.

Related: API Integration, API Tokens