MCP server

Kyo's MCP server is hosted: point a client at one URL and connect — as yourself, through Kyo's OAuth sign-in, or as one of your workspace's AI agents, with an agent key. It exposes 118 read and write tools that map 1:1 to the REST API — deals, contacts, companies, tasks, pipelines, spaces, metrics, finance, HR, documents and automations. A local copy of the server also ships inside the Kyo CLI, for clients that can only launch stdio servers. Either way, every tool call runs as whoever authorized it — bounded by the granted scopes and by that member's or agent's own workspace permissions — so a tool can never do more than they could in the app.

Hosted or local?

Use the hosted server unless you have a specific reason not to.

Setup

Hosted — sign in as yourself

Point any remote-capable MCP client at:

https://app.trykyo.com/api/mcp

The first connection opens Kyo's sign-in and consent screen in your browser. You approve the scopes there; the client registers itself with dynamic client registration and completes OAuth on its own — nothing to install, no key to paste. Clients that take the OAuth callback on their own URL scheme, like Cursor's cursor://…, are accepted alongside https and loopback callbacks. In claude.ai, add the URL under Settings → Connectors → Add custom connector. In Claude Code:

claude mcp add --transport http kyo https://app.trykyo.com/api/mcp

In Cursor, add the URL form to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kyo": { "url": "https://app.trykyo.com/api/mcp" }
  }
}

What you get is an ordinary OAuth grant: access tokens expire after an hour and the client refreshes them for you, and the grant is listed under Settings → API in Kyo, where you can revoke it.

Hosted — connect an agent with a key

When there is no person at a browser — an agent runtime, a scheduled job, CI — connect with an agent key instead. Send it as a bearer token on every request. The server accepts it wherever it accepts an OAuth token, and there is no sign-in step.

In Cursor (~/.cursor/mcp.json, with the key kept in an environment variable):

{
  "mcpServers": {
    "kyo": {
      "url": "https://app.trykyo.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:KYO_AGENT_KEY}" }
    }
  }
}

In Claude Code:

claude mcp add --transport http kyo https://app.trykyo.com/api/mcp \
  --header "Authorization: Bearer $KYO_AGENT_KEY"

From your own code it is plain MCP over Streamable HTTP: JSON-RPC POSTs to the URL with the header attached. A one-line check that a key works:

curl -X POST "https://app.trykyo.com/api/mcp" \
  -H "Authorization: Bearer $KYO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"kyo_whoami","arguments":{}}}'

initialize, tools/list and resources/list answer without a token, so a client can discover the server before it authenticates. Every tools/call needs one: a missing or rejected token gets a 401 with a WWW-Authenticate header that points at the protected-resource metadata. That is how OAuth clients know to start the sign-in — and how your agent knows its key was refused.

Local — general

The local (stdio) server is for clients that can't reach remote servers, or for when you want your tokens to live only on your machine. Every client needs the CLI installed and a one-time sign-in:

npm install -g kyo-cli
kyo login

After that, your MCP client launches the server itself from its config — you never run kyo mcp by hand. Restart the client after editing its config; the tools are discovered automatically. The local server exposes the tools bundled with the CLI version you installed, so update the CLI when new tools ship.

Claude Desktop

Add Kyo to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kyo": { "command": "npx", "args": ["-y", "kyo-cli", "mcp"] }
  }
}

Claude Code

One command from any terminal:

claude mcp add kyo -- npx -y kyo-cli mcp

Cursor

Add Kyo to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kyo": { "command": "kyo", "args": ["mcp"] }
  }
}

Other clients

Any MCP client that supports local stdio servers works. Configure it to run the command npx with arguments ["-y", "kyo-cli", "mcp"] — or simply kyo mcp if the CLI is installed globally.

Then try it: ask your agent to "list my Kyo deals" or "create a deal for Acme in the Sales pipeline."

Agent keys

An agent key connects one of your workspace's AI agents to the hosted server without a browser. A workspace admin creates it for the agent it belongs to in Settings → Agents; the key starts with kagt_ and stays valid until you revoke it. Send it as Authorization: Bearer kagt_….

• It runs as the agent. Every call is attributed to the agent — it is the created_by on records it creates and the author of its comments — and bounded by the agent's own permissions in the workspace, exactly as a person's token is bounded by theirs. To limit what a connected agent can reach, limit the agent's permissions in Kyo.
• It carries the full scope catalogue, including enrich:write. A human sign-in leaves metered enrichment opt-in; an agent key does not, so kyo_enrich_company works out of the box and spends the workspace's credits. Watch the balance with kyo_get_credit_balance.
• It is not an OAuth token. No consent screen, no refresh, no hourly expiry, and nothing under Settings → API — revoke the key itself, from where it was created. Revocation is immediate.
• Treat it like a password. Keep it in a secret manager or an environment variable, never in a repository or a prompt. A leaked key should be revoked and replaced, not rotated by hand.

Verify the connection

Before an agent writes anything, check what it is connected as. The check is the same on every surface:

Each reports whether the credential is valid, which identity it resolves to — a member or an agent — in which workspace, and the scopes it holds. If a key resolves to the wrong agent, or a sign-in to the wrong workspace, stop there and fix the credential.

Available tools

118 tools, each mapping to a REST API resource. The hosted server always serves the current catalogue; the local server serves the copy bundled with your installed CLI.

Security

• Runs as whoever authorized it — a person's grant is bounded by the scopes they approved and their own workspace permissions, including private-task visibility; an agent key is bounded by the agent's permissions. Neither can exceed what that member or agent can do in the app.
• Credentials never reach the model — the hosted server keeps OAuth tokens server-side and reads an agent key only from the request header; the local server holds your tokens on your machine. Either way only tool results are returned.
• No delete tools — v1 of the API is non-destructive, so an agent can't hard-delete your data. The only unlink-shaped tools (kyo_remove_label_from_deal, kyo_remove_space_member, kyo_unlink_person_from_deal) detach a link and leave both records intact.
• Roles and billing are off limits — kyo_update_user writes profile fields only, and no tool can change a member's role, permissions, plan or payment details.
• Enrichment is metered — kyo_enrich_company spends workspace credits and needs the enrich:write scope. Human sign-ins leave it out unless you opt in; agent keys include it.
• Revocable — end an OAuth grant with kyo logout or from Settings → API in the Kyo app; revoke an agent key from Settings → Agents.

FAQ

Is there a hosted (remote) MCP server?

Yes — https://app.trykyo.com/api/mcp, and it is the recommended way to connect. It speaks MCP over Streamable HTTP, discovers Kyo's OAuth automatically, accepts agent keys as bearer tokens, and always serves the current tool catalogue. Use the local CLI server only if your client can't reach remote servers or you want tokens to live on your machine alone.

Do I need the CLI?

No. The CLI is only needed for the local stdio server (and for using Kyo from the terminal). Every remote-capable client — claude.ai, Claude Code, Cursor, agent frameworks — connects to the hosted server directly.

Which scopes does the agent get?

With a human sign-in, whatever you granted: on the hosted server that's the consent screen shown at connect time; on the local server it's kyo login (re-run with --scope "…" to grant more or less). The default grant is full read/write across every scope the API has except enrich:write, which stays opt-in because it spends credits. With an agent key, the full catalogue including enrich:write. Whatever the scopes, a call still can't exceed the authorizing member's or agent's permissions in the workspace. Call kyo_whoami to see exactly what a connection holds.

Can an agent delete my data?

No. There are no delete tools, and the underlying API has no DELETE in v1.

Which clients are supported?

The hosted server works with claude.ai connectors, Claude Code, Cursor, and any MCP client that supports remote servers — with OAuth for people, or a static Authorization header for agent keys. The local server works with Claude Desktop, Claude Code, Cursor, and any client that can launch stdio servers.