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.

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
kosmokrator mcp:add github --project --type=stdio \
  --command=github-mcp-server --env GITHUB_TOKEN --json

# Write ~/.kosmokrator/mcp.json
kosmokrator 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
kosmokrator mcp:import .vscode/mcp.json --project --json

# Export effective config in either shape
kosmokrator mcp:export --format=mcpServers --json
kosmokrator 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
kosmokrator mcp:preset list --json

# Add a project-level preset
kosmokrator mcp:preset add tavily --project --json
kosmokrator mcp:preset add firecrawl --project --json
kosmokrator mcp:preset add exa --project --json
kosmokrator mcp:preset add fetch --project --json
kosmokrator 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
kosmokrator mcp:list --json
kosmokrator mcp:status --json
kosmokrator mcp:trust github --project --json
kosmokrator mcp:tools github --json
kosmokrator mcp:schema github.search_repositories --json

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

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

# JSON payload
printf '%s\n' '{"query":"kosmokrator"}' | \
  kosmokrator 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
kosmokrator mcp:lua --eval 'dump(app.mcp.github.search_repositories({
  query = "kosmokrator"
}))' --json

# Shared integration Lua endpoint also exposes app.mcp.*
kosmokrator 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" | \
  kosmokrator mcp:secret:set github env.GITHUB_TOKEN --stdin --json

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

kosmokrator mcp:secret:list github --json
kosmokrator 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:

kosmokrator 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.

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

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

# Trusted automation can bypass MCP trust and read/write policy for one call.
kosmokrator 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:doctor, mcp:examples	Agent-friendly diagnostics and examples.