Connectors — MCP

Overview

kode mcp is a stdio MCP server. An MCP client starts it as a program and calls the tools of one desk through it. The server serves every workspace, environment, and workspace tool of the desk. Each tool names its target with workspace or env, as an id. No command, file read, or file write runs on your computer. The client keeps its own local tools.

Nothing is current. Every call that acts in a desk names it in desk (id, name, or team/name); a call without desk is refused with pass `desk` (id or name); `desk` `list` shows yours. desk list and desk create need no desk.

Tools

The client gets the tools of the desk: the desk, workspace, code, package, image, environment, volume, account, web, and board tools. Every tool, with its arguments and its API route, is in Agent tools. Every tool except desk list and create takes a required desk. The desk tool has the actions list (your desks, each with its environment), create (makes a desk, and connects environment if given; it moves nothing), connect (sets the environment of desk; null disconnects it), start, stop, delete, and ttl.

Add the kode skill to the client too, if the client reads skills. The skill tells the agent which tool does which job. See Skills.

Sign-in and limits

The server uses the login of kode login, saved in ~/.config/kode. It needs no token in the client settings. Every call acts as you, with your rights and limits. A call over a quota gets the same 409 as any other client, and a paused team access gets 403. See Limits.

The server writes stdout for the client only. Its messages for you go to stderr. If the link to the desk drops, the server stays up and connects again after 5 seconds. A call that the dropped link carried returns an error, and the client repeats it.

Remote server

https://dev.kloudlite.io/mcp is the same server on the internet. An app that cannot start a program on your computer (claude.ai, the Claude desktop and mobile apps, ChatGPT) connects to it. The desktop client's CLI can use it too. You sign in with your Kode account on a consent page. You need no laptop and no kode login.

The connection acts through the desk, with your rights and limits. It holds no credential for /v1. Every call checks each team. A team that you left stops within 30 seconds. A paused team gives a tool error that names the pause.

Tasks

Add the server to an MCP client

Reason for the task

Give an MCP client the tools of a desk.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: kode is installed and you are signed in. See Install kode.
• References: kode mcp.

Procedure

1. Add the server to the client. For Claude Code, run this command.

   CLICopy

   claude mcp add kd -- kode mcp

2. Add this entry to mcpServers for a client with a JSON settings file.

   jsonCopy

   {  "mcpServers": {    "kd": { "command": "kode", "args": ["mcp"] }  }}

3. Add this table to ~/.codex/config.toml for Codex.

   tomlCopy

   [mcp_servers.kl]command = "kode"args = ["mcp"]

4. Add the team to the arguments to serve another team, for example ["mcp", "acme"].

5. Close the client and open it again.

Close-out

1. Make sure that the client lists the server kd as connected and shows its tools.

Connect a desk to an environment

Reason for the task

Set the environment that a desk reaches.

Job set-up

• Access: you.
• Agent tool: desk
• Conditions: the server kd is connected.
• References: PUT /v1/desks/{id}/environment, GET /v1/desks.

Procedure

1. Find the desk by name or id.

   AI agentCopy

   {"tool": "desk", "arguments": {"action": "list"}}

2. Connect the desk to an environment with environment, by id or name. environment set to null disconnects it.

   AI agentCopy

   {"tool": "desk", "arguments": {"action": "connect", "desk": "dev", "environment": "api"}}

Close-out

1. Run desk with action set to list. Make sure that the desk shows the environment.

Show the desk

Reason for the task

Find the desk that the tools drive, and its environment.

Job set-up

• Access: you.
• Agent tool: desk
• Conditions: the server kd is connected.
• References: GET /v1/desks/{id}.

Procedure

1. Show the desk.

   AI agentCopy

   {"tool": "desk", "arguments": {"action": "list"}}

Close-out

1. Make sure that the answer names the desk that you expect. If it does not, connect the desk.

Add the connector in claude.ai

Reason for the task

Give claude.ai, and the Claude desktop and mobile apps of the same account, the tools of a desk.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: you are signed in to Kode in this browser.
• References: OAuth endpoints.

Procedure

1. Open Customize in claude.ai, then Connectors, then Add custom connector.
2. Enter the name Kode and the URL https://dev.kloudlite.io/mcp.
3. Keep the sign-in choice "Use Claude's published identity". Select "Register automatically" if the first choice fails.
4. Select Connect. Select the teams on the consent page, then select Approve.

Close-out

1. Run desk with action set to list in a chat. Make sure that it lists your desks.
2. If it says that there is no desk, ask the app to make one with desk and action set to create.

Add the server to the desktop client's CLI

Reason for the task

Give the desktop client's CLI the tools of a desk without a program on your computer.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: the CLI is installed and you are signed in to Kode in the browser.
• References: OAuth endpoints.

Procedure

1. Add the server.

   CLICopy

   claude mcp add --transport http kl https://dev.kloudlite.io/mcp

2. Run /mcp in the client, select kd, then sign in.

3. Select the teams on the consent page in the browser, then select Approve.

Close-out

1. Run /mcp. Make sure that kd is connected.

Add the server to ChatGPT

Reason for the task

Give ChatGPT the tools of a desk.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: your ChatGPT plan offers "Add custom MCP server". This is documented for Business, Enterprise, and Edu plans.
• References: OAuth endpoints.

Procedure

1. Open chatgpt.com/plugins, select +, then Add custom MCP server.
2. Enter the URL https://dev.kloudlite.io/mcp and select OAuth for the sign-in.
3. Select Create as a plugin. Sign in on the consent page, select the teams, then select Approve.

Close-out

1. Run desk with action set to list in a chat. Make sure that it lists your desks.
2. If it says that there is no desk, ask the app to make one with desk and action set to create.

Revoke a connection

Reason for the task

Stop an app from using your desks.

Job set-up

• Access: you.
• Agent tool: none; an agent uses the SDK.
• Conditions: none.
• References: DELETE /v1/oauth/grants/{id}.

Procedure

1. Open Settings, then Connected apps.
2. Select Disconnect for the app, then confirm.

Close-out

1. Make sure that the app is gone from the list. The next call of the app asks it to sign in again.

Troubleshooting