Skip to main content

Clients

Any client that speaks Streamable HTTP MCP and can run the MCP OAuth 2.1 flow can connect. You only give it the URL; the client finds where to authenticate on its own, opens the Kobana login in the browser and keeps the token — see Authentication.

A client without OAuth support connects too, with a personal token: create it in Kobana Account → Tokens and Access → New Personal Token, with the app Autonomous Inbox and the use MCP, and configure the client to send it as Authorization: Bearer <token>. It is also the way for an agent that needs to write, since the OAuth flow grants read-only access today.

When your organization has more than one workspace, pick one per connection with the X-Workspace-Id header.

Claude Code​

claude mcp add --transport http kobana-inbox https://mcp.inbox.kobana.com.br

Then run /mcp in a session and choose Authenticate to log in to Kobana.

With a personal token, without the OAuth flow:

claude mcp add --transport http kobana-inbox https://mcp.inbox.kobana.com.br \
  --header "Authorization: Bearer <personal token>"

Clients configured by file​

Clients that read a JSON configuration file take the URL and the transport. Through the OAuth flow there is no authentication header:

{
  "mcpServers": {
    "kobana-inbox": {
      "type": "http",
      "url": "https://mcp.inbox.kobana.com.br"
    }
  }
}

On the first connection the client opens the browser for you to authorize. You pick the organization on the consent screen, and it is recorded in the token.

With a personal token, add the headers — the organization is the one of the account where you created the token:

{
  "mcpServers": {
    "kobana-inbox": {
      "type": "http",
      "url": "https://mcp.inbox.kobana.com.br",
      "headers": {
        "Authorization": "Bearer <personal token>",
        "X-Workspace-Id": "<workspace-id>"
      }
    }
  }
}

X-Workspace-Id is only needed when your organization has more than one workspace. Treat the file as a secret: whoever reads it uses the token.

Clients that connect by URL​

Claude and ChatGPT connect a remote server by pasting https://mcp.inbox.kobana.com.br into their connector settings. The OAuth flow runs inside the app.

Using other Kobana servers alongside​

Tools here are unprefixed (emails_list), and resources live under kobana://inbox/; the other Kobana MCP servers prefix theirs (billing_, finance_, kobana://billing/, kobana://finance/). They sit in the same client without colliding.

  • Authorize with the right account. Tools are narrowed to what the person who authorized can do in the dashboard. A client authorized by a read-only analyst exposes only the read tools, whatever the model on the other side tries. It is the strongest way to restrict an agent.
  • Keep the token read-only. A token carrying resource scopes but not the write verb physically cannot change anything. The OAuth flow is read-only by construction; in a personal token, tick write only on the resources the agent must change.
  • Personal token: short validity, minimum scope. Revoking it in Kobana does not cut access before it expires — see Personal token revocation.
  • Keep the destructive tools out unless you need them. Deletes, outbound actions (webhook test and replay, e-mail reprocess), secret rotation and allow-list changes require the write verb and a permission that an organization administrator grants explicitly, and the server asks the user to confirm each one — only a client on protocol 2026-07-28 with elicitation forms can run them.

Local stdio servers​

The repository also ships seven stdio MCP servers, one per resource (workspaces, inboxes, emails, agents, agent-runs, webhooks, system-events). They run on your machine, talk to the public API over HTTPS and use the full REST authentication stack — JWT, mTLS client certificate and origin secret.

They remain a valid option and are not replaced by this server. Use them when you already hold a client certificate and want the minimum scope enforced by running only the server you need; use the remote server when you cannot distribute a certificate to the client.