MCP

KosmoKrator can use Model Context Protocol servers from the same project-level .mcp.json files used by other coding agents. MCP servers are exposed through headless CLI commands and through Lua as app.mcp.*; they are not registered as native model tools.

Recommended agent flow: mcp:list --json, review the server command, mcp:trust SERVER --project --json, mcp:tools SERVER --json, mcp:schema SERVER.TOOL --json, then mcp:call SERVER.TOOL --json or mcp:lua. In agent Lua code mode, use lua_read_doc page="mcp.SERVER" before calling app.mcp.SERVER.TOOL(...).

PHP applications can use the same runtime through the Agent SDK: $agent->mcp()->call(...), $agent->mcp()->lua(...), and runtime-only ->withMcpServer(...) overlays.

KosmoKrator as an MCP Gateway

KosmoKrator can also run in the opposite direction: as one stdio MCP server for clients such as Claude Code. The gateway exposes selected KosmoKrator integrations and selected upstream MCP servers without making the user configure each integration as a separate MCP server.

The most direct Claude Code project config is:

{
  "mcpServers": {
    "kosmo": {
      "type": "stdio",
      "command": "kosmo",
      "args": [
        "mcp:serve",
        "--integration=plane",
        "--integration=clickup",
        "--upstream=context7",
        "--write=deny"
      ]
    }
  }
}

The selected tools are encoded directly in the MCP config. Use repeated flags or comma-separated values:

kosmo mcp:serve \
  --integration=plane \
  --integration=clickup \
  --upstream=context7 \
  --write=deny

kosmo mcp:serve \
  --integrations=plane,clickup \
  --upstreams=context7,github \
  --write=allow

--write=deny is the default and hides write-capable integration and upstream MCP tools. Use --write=allow only for a trusted Claude Code project where writes should execute headlessly. Upstream MCP servers still use KosmoKrator’s project trust and permission checks unless the gateway is started with --force.

Generate a ready-to-paste config:

kosmo mcp:gateway:export \
  --integration=plane \
  --upstream=context7 \
  --write=deny \
  --json

Install the gateway into the current project’s .mcp.json:

kosmo mcp:gateway:install \
  --integration=plane \
  --upstream=context7 \
  --write=deny \
  --json

For reusable local presets, define a profile in KosmoKrator config and reference it from .mcp.json:

kosmo:
  mcp_gateway:
    profiles:
      claude:
        integrations:
          include: [plane, clickup]
        upstream_mcp:
          include: [context7]
        write_policy: deny
        expose_resources: true
        expose_prompts: true
        max_result_chars: 50000

{
  "mcpServers": {
    "kosmo": {
      "type": "stdio",
      "command": "kosmo",
      "args": ["mcp:serve", "--profile=claude"]
    }
  }
}

Tool names are deterministic:

Source	Gateway tool name
plane.list_issues	integration__plane__list_issues
clickup.create_task	integration__clickup__create_task
context7.resolve_library_id	mcp__context7__resolve_library_id

The gateway intentionally ignores a configured KosmoKrator mcp:serve upstream so a project .mcp.json cannot accidentally proxy itself recursively.

Portable Config

Project MCP servers live in .mcp.json using the common mcpServers shape:

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

KosmoKrator also reads VS Code style .vscode/mcp.json and Cursor style .cursor/mcp.json files with a top-level servers object. Effective precedence is global config first, then project compatibility files, then project .mcp.json.

# Write project .mcp.json
kosmo mcp:add github --project --type=stdio \
  --command=github-mcp-server --env GITHUB_TOKEN --json

# Write ~/.kosmo/mcp.json
kosmo mcp:add context7 --global --type=stdio \
  --command=npx --arg=-y --arg=@upstash/context7-mcp --json

# Import a VS Code or Cursor file into .mcp.json
kosmo mcp:import .vscode/mcp.json --project --json

# Export effective config in either shape
kosmo mcp:export --format=mcpServers --json
kosmo mcp:export --format=vscode --path=.vscode/mcp.json --json

Web Provider Presets

For common web-search MCP servers, mcp:preset writes a portable server entry without making you remember package names.

# List available presets
kosmo mcp:preset list --json

# Add a project-level preset
kosmo mcp:preset add tavily --project --json
kosmo mcp:preset add firecrawl --project --json
kosmo mcp:preset add exa --project --json
kosmo mcp:preset add fetch --project --json
kosmo mcp:preset add parallel --project --json

Presets use environment placeholders such as ${TAVILY_API_KEY}. Store shared project config in .mcp.json and keep actual secrets in the shell environment or with mcp:secret:set.

Headless Calls

# Discovery
kosmo mcp:list --json
kosmo mcp:status --json
kosmo mcp:trust github --project --json
kosmo mcp:tools github --json
kosmo mcp:schema github.search_repositories --json

# Generic call
kosmo mcp:call github.search_repositories \
  --query="kosmokrator language:php" --json

# Server shortcut
kosmo mcp:github search_repositories \
  --query="kosmokrator language:php" --json

# JSON payload
printf '%s\n' '{"query":"kosmokrator"}' | \
  kosmo mcp:call github.search_repositories --json

All command JSON envelopes include success. Runtime calls return non-zero exit codes when config, trust, permission, transport, schema, or server execution fails.

Lua Mode

# Dedicated MCP Lua endpoint
kosmo mcp:lua --eval 'dump(app.mcp.github.search_repositories({
  query = "kosmokrator"
}))' --json

# Shared integration Lua endpoint also exposes app.mcp.*
kosmo integrations:lua workflow.lua --json

Agent-side execute_lua sees the same app.mcp.* namespace alongside app.integrations.* and app.tools.*.

local repos = app.mcp.github.search_repositories({
  query = "kosmokrator language:php"
})
dump(repos)

Lua helper functions are available for discovery and non-tool MCP surfaces:

dump(mcp.servers())
dump(mcp.tools("github"))
dump(mcp.schema("github.search_repositories"))
dump(mcp.resources("github"))
dump(mcp.read_resource("github", "resource://..."))
dump(mcp.prompts("github"))
dump(mcp.get_prompt("github", "summarize", { text = "..." }))

Secrets

Do not commit tokens into .mcp.json. Use environment variables for shared files or KosmoKrator’s MCP secret store for headless machines.

printf %s "$GITHUB_TOKEN" | \
  kosmo mcp:secret:set github env.GITHUB_TOKEN --stdin --json

kosmo mcp:add github --project --type=stdio \
  --command=github-mcp-server \
  --env GITHUB_TOKEN='${KOSMO_SECRET:mcp.github.env.GITHUB_TOKEN}' \
  --json

kosmo mcp:secret:list github --json
kosmo mcp:secret:unset github env.GITHUB_TOKEN --json

Trust And Permissions

Project MCP config can spawn arbitrary commands. KosmoKrator requires project MCP servers to be trusted before normal headless discovery or execution. Review .mcp.json, then run:

kosmo mcp:trust github --project --json

Read/write policy is separate from trust. Unknown MCP tools default to write unless the server marks them with MCP readOnlyHint.

kosmo mcp:add github --project --read=allow --write=ask --json

# Headless ask cannot show a modal, so this fails unless write is allowed.
kosmo mcp:call github.create_issue --title="..." --json

# Trusted automation can bypass MCP trust and read/write policy for one call.
kosmo mcp:call github.create_issue --title="..." --force --json

Command Reference

Command	Purpose
mcp:list	List effective MCP servers and source paths.
mcp:status	Show configured/disabled status without starting servers.
mcp:add, mcp:remove, mcp:enable, mcp:disable	Manage portable MCP config.
mcp:trust	Trust the current project server fingerprint.
mcp:tools, mcp:schema	Discover callable MCP tools.
mcp:call, mcp:<server>	Call MCP tools headlessly.
mcp:lua	Run Lua with app.mcp.*.
mcp:resources, mcp:resource	List/read MCP resources.
mcp:prompts, mcp:prompt	List/get MCP prompts.
mcp:secret:*	Set/list/unset MCP secrets without echoing values.
mcp:import, mcp:export	Move between mcpServers and VS Code servers shapes.
mcp:serve	Run KosmoKrator as a stdio MCP gateway exposing selected integrations and upstream MCP servers.
mcp:gateway:export, mcp:gateway:install	Generate or install a Claude-compatible KosmoKrator gateway .mcp.json entry.
mcp:doctor, mcp:examples	Agent-friendly diagnostics and examples.