MCP

Description and operation

General

kloudlite mcp is a stdio MCP server. An MCP client, for example Claude Code, starts it as a program and calls the agent tools of one session through it. The server serves every workspace, environment and workspace tool of the session. Each tool names its target with workspace or env. No command, file read or file write runs on your computer.

The server picks the session in this order: --session, the session that you selected with kloudlite sessions use (saved in session.json in ~/.config/kloudlite), your only session. With more than one session and none selected, the server lists one tool, session_pick, until the agent picks a session. With no session, it creates the session main with no environment.

The server adds two tools for the session of your computer. session_current shows the session and its environment. session_use picks another session, and can connect it to an environment. The client then loads the tools again. The server writes stdout for the client only. The messages for you go to stderr.

If the link to the session 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. If the session ended, the server picks a session again, in the same order.

Tasks

Add the server to an MCP client

Reason for the task: Give an MCP client the tools of a session.

Job set-up

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

Procedure

1. Add the server to Claude Code. Other clients take the same command and arguments in their MCP settings.

   CLICopy

   claude mcp add kl -- kloudlite mcp

2. Add the team and the session to the command to serve a session other than the default.

   CLICopy

   claude mcp add kl -- kloudlite mcp acme --session dev

3. Close the client and open it again.

Close-out

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

Pick the session

Reason for the task: Point the tools at the session you want to work in.

Job set-up

• Access: you.
• Agent tool: session_use
• Conditions: the server kl is connected.
• References: kloudlite sessions use, GET /v1/sessions.

Procedure

1. Select the session by name or id. Add team for a team session.

   AI agentCopy

   {"tool": "session_use", "arguments": {"name": "dev"}}

2. Connect the session to an environment with environment (an existing environment, by id or name). Use new_environment (a name) to create one instead.

   AI agentCopy

   {"tool": "session_use", "arguments": {"name": "dev", "environment": "api"}}

Close-out

1. Run session_current. Make sure that it names the session.

Show the session

Reason for the task: Find the session that the tools drive, and its environment.

Job set-up

• Access: you.
• Agent tool: session_current
• Conditions: the server kl is connected.
• References: GET /v1/sessions/{id}.

Procedure

1. Show the session.

   AI agentCopy

   {"tool": "session_current", "arguments": {}}

Close-out

1. Make sure that the answer names the session that you expect. If it does not, pick the session.

Troubleshooting