Kortix MCP server

Add Kortix to Claude, ChatGPT, Cursor, VS Code or Codex with one URL, and drive sessions, sandboxes, connectors and the API from there.

The Kortix MCP server lets an AI client such as Claude, ChatGPT, Cursor, VS Code or Codex use Kortix. The client starts and follows sessions, runs commands in their sandboxes, calls your connectors and reaches the whole Kortix API. It acts as you, with your permissions. You install nothing.

Add Kortix to your client

Add this URL to your client:

https://api.kortix.com/v1/mcp

On a self-hosted instance, the URL is <your API URL>/v1/mcp. The URL names no project. The client reaches every account and project you can open, the same reach as the CLI. Most tools take a project_id or a session_id. list_projects lists your projects and their ids.

In the web app, open the project menu (top left) and select Connect MCP, or select the Connect MCP row in the sidebar. The dialog shows the URL for your instance, with a copy or install action for Claude, Claude Code, Cursor, Codex and any other MCP client.

claude mcp add --transport http kortix https://api.kortix.com/v1/mcp

{ "mcpServers": { "kortix": { "url": "https://api.kortix.com/v1/mcp" } } }

{ "servers": { "kortix": { "type": "http", "url": "https://api.kortix.com/v1/mcp" } } }

codex mcp add kortix --url https://api.kortix.com/v1/mcp
codex mcp login kortix

Sign in and revoke

The client signs you in with OAuth on its first call. Your browser opens the Kortix consent screen. The screen names the app and where it returns you. A client that registered itself is marked Unverified app. Approve it only when you connect it yourself.

Use a personal access key instead. A client without OAuth, or a script, sends a kortix_pat_ key as Authorization: Bearer. Create one with kortix tokens new <name> or under Settings → Personal access keys. A key does not expire unless you set --expires (for example --expires 90d). A key made with --project <id> reaches that one project only.

In an mcpServers config, such as Cursor:

{ "mcpServers": { "kortix": { "url": "https://api.kortix.com/v1/mcp", "headers": { "Authorization": "Bearer kortix_pat_…" } } } }

For Codex, put the key in an environment variable and name it in ~/.codex/config.toml:

[mcp_servers.kortix]
url = "https://api.kortix.com/v1/mcp"
bearer_token_env_var = "KORTIX_TOKEN"

Revoke a client. Go to Settings → Personal access keys → Connected apps and select Revoke access. The list holds every app you approved, across all your accounts. The app’s tokens stop working at once, and it must ask you again. From a terminal:

kortix tokens apps ls
kortix tokens apps rm <client-id>

Manage connected apps from a browser session or a personal access key that is not bound to a project. Revoking an app does not revoke your personal access keys.

What a connected app cannot do. A kortix_oat_ token reads and changes what you can. It cannot create a credential that outlives it: personal access keys, project CLI tokens, gateway keys, SCIM tokens, OAuth clients and their secrets, and service accounts answer 403. It cannot list or revoke connected apps.

The audit log records each call with its credential: credential_kind is oauth_app (with the app) for an OAuth connection, or personal_access_token for a key. Every call passes the same authorization as the web app.

What the tools do

The server has 23 tools. Your client reads their parameters from the server.

Sessions

• list_projects: every project you can open, with its project_id, account, repository and your role. Start here.
• start_session: starts a session in a project with a first prompt. Optional: name, agent, labels (at most 20, each 1-64 characters) and metadata (a JSON object, at most 16,384 characters). Returns the session_id.
• send_message: queues a message for a session. A stopped session starts.
• read_session: the session status, the turn state (idle, booting, running or queued) and the latest messages with tool inputs and outputs. limit is 10 by default, 100 at most. wait_seconds (at most 45) waits for the turn to end. Only idle means the agent is done.
• list_sessions: the top-level sessions of a project, 20 by default, 200 at most. Filter with started_by (me, others or automated), query (1-200 characters), labels and parent_session_id (the children of one session). Pass next_cursor back as cursor for the next page.

Sandbox

• run_command: runs a bash command in a session’s sandbox. cwd is /workspace by default. timeout_seconds is 600 by default, 86,400 at most. A command that times out exits with 124.
• read_file: reads a file. With session_id, from the live sandbox, limited to /workspace, the home directory (~) and /tmp. With project_id and an optional ref, from the project’s git repository, without a sandbox.
• write_file: writes a file in a session’s sandbox and creates parent directories. encoding is utf8 (default) or base64.
• list_files: lists one sandbox directory, or every repository file under a path.

A stopped sandbox starts on the first sandbox call. In read_file and write_file, a relative path resolves under /workspace, the session’s git checkout. ~ is the sandbox home.

Long commands. One run_command call waits about 50 seconds. If the command still runs, the result has status: running, a job_id and the output so far. Call run_command with the job_id to keep waiting, or with job_id and cancel: true to stop it. The result shows the last 24,000 bytes of each stream. The full output stays in ~/.cache/kortix-mcp/jobs/<job_id>/ in the sandbox for at least 24 hours. A restarted sandbox loses its jobs.

Guides

• read_skill: the Kortix platform guides. name=kortix-system is the complete reference. With project_id, the project’s own skills come first.

Connectors

The same flow as kortix connectors:

• list_connectors, search_connector_actions, describe_connector_action: find what is connected and an action’s arguments.
• call_connector: runs an action as you. Pass account when a connector has several accounts and no default. Pass reason on a write whose arguments are only ids. A pending_approval result carries an approval_url: a person approves, then the client calls again with the same tool, arguments and account within 15 minutes. See Policies and approvals.
• upload_connector_attachment: stages a file for a call and returns the ref to put in args.
• connect_connector: returns the URL a person opens to connect an account. owner is me (default) or project.
• search_connector_apps: finds an app to add.
• add_connector, remove_connector: change the project’s connectors. Each change commits to kortix.yaml on the project’s default branch.

API

• search_api, describe_api, call_api: find, read and call any /v1/ route as you. project_id fills {projectId} in the path. call_api refuses /v1/oauth/* and MCP paths. The routes are in the REST API reference.

CLI

• kortix: runs a CLI command as you. See the next section.

The kortix tool

The kortix tool runs the real kortix CLI on the server with your token. Every CLI command works through it, except the refused commands below.

• args is the argv after kortix, one element per argument, at most 64. It is never a shell line.
• project_id sets the project of a project-scoped command. session_id sets the session of a command that acts on one.
• Discover commands with ["--help"] and ["<group>", "--help"]. Add --json to output you parse.

{ "name": "kortix", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }

The result is JSON: exit_code, stdout (or json, the parsed value of JSON output), and stderr. A non-zero exit_code marks the result as an error. stdout is cut at 45,000 bytes and stderr at 8,000 bytes. stdout is cut further so that the whole result stays under 55,000 characters. The result then has truncated. Cut JSON is not valid JSON: narrow the command. A command is killed after about 45 seconds, and the result has timed_out. Each API process runs at most 4 kortix commands at once. A call over that limit returns Busy: call again.

The tool refuses these commands before anything runs. The error names the alternative.

Sessions, sandbox files and connectors have their own tools. Prefer them to the kortix tool.

Limits

This server vs MCP connectors

This server is the inbound direction: your AI client calls Kortix. A connector with provider: mcp is the outbound direction: a Kortix agent calls someone else’s MCP server through the Kortix gateway, and the sandbox never holds the credential. To add one, see Connectors.