MCP Server - Komos Documentation

Komos exposes an MCP (Model Context Protocol) server that lets AI coding agents run automations, check results, and talk to Moss directly from your IDE.

Setup

Create a personal token

Go to Settings → Developer → Personal Tokens and click Create token. Copy the token — you won’t be able to see it again.

Add to your agent

Claude Code
Claude Desktop
Codex
Gemini CLI

claude mcp add komos -- npx -y mcp-remote \
  https://api.komos.ai/public/v1/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

Add to your Claude Desktop config file:macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "komos": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.komos.ai/public/v1/mcp/",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.komos]
url = "https://api.komos.ai/public/v1/mcp/"
bearer_token_env_var = "KOMOS_API_KEY"

Then set the environment variable:

export KOMOS_API_KEY=YOUR_TOKEN

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "komos": {
      "httpUrl": "https://api.komos.ai/public/v1/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Available tools

Tool	Description
`list_tasks`	List automation tasks in your workspace. Supports search, pagination, and status filter.
`get_task`	Get full details of a task including its definition, inputs, outputs, and schedules.
`run_task`	Start a task run with optional input variables. Returns the run ID.
`get_run`	Get the status, outputs, and details of a task run. Pass `include_logs: true` for node-level execution logs with tool calls and payloads.
`list_runs`	List recent task runs. Filter by task or status.
`list_skills`	List reusable skills (agent instructions) in your workspace.
`get_skill`	Get full details of a skill including its instructions.
`list_credentials`	List stored credentials (names and domains only, no secrets).
`list_integrations`	List connected integrations (e.g., Gmail, Slack) with their status.
`ask_moss`	General-purpose catch-all: ask Moss, your AI automation engineer, to do anything on the platform (create tasks, configure integrations, debug runs, etc.). Prefer specific tools above when possible; use `ask_moss` for complex or multi-step requests that don’t fit a single tool.

Using ask_moss

Moss can do anything you can do on Komos: create tasks, configure integrations, set up schedules, and build automations. Examples:

“Create a task that scrapes example.com/pricing every morning”
“Set up a Slack notification when my weekly report task fails”
“Connect my Google Sheet and create a task that updates it daily”

Moss maintains conversation context. Pass the conversation_id from a previous response to continue the conversation:

ask_moss("Also add email notification when price drops", conversation_id="abc-123")

Background jobs

For complex tasks, Moss may dispatch a background job. When this happens, the tool returns immediately with a message like “I’ve dispatched a background job to set this up.” Follow up with another ask_moss call to check the result.

Authentication

Personal tokens are scoped to your user account and organization. They inherit your role and permissions.

	Org API Keys	Personal Tokens
Created by	Admins only	Any member
Use case	CI/CD, server integrations	MCP, developer tools
Scope	Organization	Organization + User
Can use Moss	No	Yes

​Setup

​Available tools

​Using ask_moss

​Background jobs

​Authentication

Setup

Available tools

Using ask_moss

Background jobs

Authentication