| name | chutes-mcp-portability |
| description | Make Chutes.ai available to any agent via MCP or OpenAI-compatible configs. Use this skill when the user wants to plug Chutes into Cursor, Cline, Aider, Claude Desktop, Hermes, or another agent. The skill installs the Chutes MCP server (stdio), writes per-agent config snippets, and runs a health check. Triggers on: MCP chutes, chutes MCP server, cursor chutes, cline chutes, aider chutes, claude desktop chutes, hermes chutes provider, openai-compatible chutes, drop-in chutes config, portable chutes, chutes for my agent. |
chutes-mcp-portability
Status: VERIFIED LIVE 2026-04-13 via docs/chutes-maxi-wave-2.md Track C.2 + C.6. chutes-mcp-server --self-check passed, and 7 read tools were exercised against a real cpk_ with non-empty responses.
Refresh 2026-06-11: auth headers re-verified live — Authorization: Bearer cpk_... now returns 200 on llm.chutes.ai/v1/models, on a real paid POST /v1/chat/completions (live completion returned), and on api.chutes.ai/users/me (the April finding is inverted; see auth note below). The server's inference calls now send Bearer. Catalog re-verified: 13 models, all -TEE / confidential_compute: true. chutes-mcp-server --self-check passed live on 2026-06-11 (run via uvx from the local path). That run also caught and fixed a pre-existing packaging bug: pyproject.toml declared readme = "README.md" which didn't exist, so every uv tool install --from build failed with "Readme file does not exist" — mcp-server/README.md now exists and the install builds.
Read tools graduated out of BETA (verified): chutes_list_models, chutes_get_quota, chutes_list_aliases, chutes_list_chutes, chutes_get_usage, chutes_get_discounts, chutes_list_api_keys.
Read tools still BETA (not exercised through the MCP path): chutes_chat_complete (paid — the underlying POST /v1/chat/completions + Bearer auth were live-verified 2026-06-11 via direct curl, but the tool itself has not been exercised through MCP, so the label stays), chutes_get_evidence (needs a specific chute_id), chutes_oauth_introspect (needs a live OAuth token).
Write tools — permanent BETA under the deploy-features policy: chutes_deploy_vllm, chutes_deploy_diffusion, chutes_teeify, chutes_set_alias, chutes_delete_alias, chutes_create_api_key. The set/delete alias pair was functionally exercised live during wave 2 (round-trip passed) but stays BETA per policy — deploy-side writes always keep the label. MCP tool descriptions prepend [BETA] so clients display it.
What this skill does
Makes Chutes usable from any agent environment with one of two mechanisms:
- MCP server (
mcp-server/server.py). Stdio transport. Exposes Chutes management + inference as MCP tools. Any MCP-aware client (Claude Desktop, Cursor, Cline, Claude Code itself) can load it.
- Config snippets (
scripts/generate_agent_config.py). For clients that don't speak MCP but do speak OpenAI-like HTTP. These are now true drop-ins auth-wise — Bearer on a paid POST /chat/completions was live-verified 2026-06-11 — but each snippet stays [BETA] until a completion round-trip is exercised through that specific client.
Both paths read secrets from the keychain via manage_credentials.py and never echo cpk_ into transcripts.
Live auth finding (re-verified 2026-06-11 — this inverts the wave-3 2026-04-15 finding):
Authorization: Bearer cpk_... → 200 on GET llm.chutes.ai/v1/models, on a real paid POST llm.chutes.ai/v1/chat/completions (live completion returned), AND on GET api.chutes.ai/users/me. Bearer is the platform-recommended header per chutes.ai's own ai-plugin.json and llms.txt.X-API-Key: cpk_... → 200 on GET /v1/models (which is now public, so this proves little) but 401 on api.chutes.ai/users/me. On the inference surface it is confirmed silently ignored (live 2026-06-11): a completion POST with it got the anonymous nginx 429, byte-identical to a fully unauthenticated POST, while Bearer succeeded in the same minute. Do not use it.GET /v1/models requires no auth at all.- The fingerprint→JWT flow (
POST /users/login) is still what the MCP server uses for management writes; Bearer-cpk behavior on management writes is unverified as of 2026-06-11.
The MCP server in this repo now sends Bearer on the inference surface and keeps the fingerprint→JWT path for management tools.
Supported targets
| Target | Mechanism | Notes |
|---|
| Claude Desktop | MCP | Writes to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS path; shown for other OSes). Claude Desktop also supports one-click MCP Bundles (.mcpb) for local servers — not packaged here yet (unverified as of 2026-06-11) |
| Claude Code | MCP | claude mcp add equivalent or direct config snippet |
| Cursor | MCP | .cursor/mcp.json at the workspace root (or ~/.cursor/mcp.json for global) |
| Cline | MCP | Global cline_mcp_settings.json via Cline's MCP Servers → Configure UI (not VS Code settings.json) |
| Aider | OpenAI-compat | ~/.aider.conf.yml with openai-api-base + model allowlist |
| Hermes | OpenAI-compat + MCP | Refreshes other-agents/hermes/config-examples/*.yaml; Hermes can also add the stdio MCP server with hermes mcp add chutes --command chutes-mcp-server |
| Generic OpenAI SDK | OpenAI-compat | Prints an env var block |
| System-prompt agents | prompt | Writes a paste-able instruction block to other-agents/system-prompt/ |
Walkthrough
Step 1 — pick targets
Ask the user which targets to configure. Multi-select is normal ("Cursor and Aider").
Step 2 — install the MCP server (for MCP targets only)
uv tool install chutes-mcp-server --from plugins/chutes-ai/skills/chutes-mcp-portability/mcp-server
pipx install plugins/chutes-ai/skills/chutes-mcp-portability/mcp-server
This gives the user a chutes-mcp-server command on PATH. Local-path install only: chutes-mcp-server is NOT published on PyPI (404 verified 2026-06-11), so the --from <local path> form is required — a bare uv tool install chutes-mcp-server will fail. (Fixed 2026-06-11: the --from build itself used to fail with "Readme file does not exist" because pyproject.toml declared a README.md that wasn't checked in; the README now exists.) The command reads CHUTES_API_KEY from env or falls back to manage_credentials.py get --field api_key for inference (sent as Authorization: Bearer). For management tools, it uses CHUTES_FINGERPRINT or the stored fingerprint to mint a short-lived JWT via POST /users/login.
Step 3 — generate configs
python <skill-scripts-dir>/generate_agent_config.py --target cursor,aider,hermes
--target accepts a comma-separated list. For each target, the script:
- Reads
cpk_ from the keychain to inject into env-var-style targets.
- Writes config files to each target's conventional location or, for Hermes, refreshes the checked-in examples in
other-agents/hermes/config-examples/.
- Prints next-step commands (restart the client, reload window, etc.).
Step 4 — health check
For MCP targets:
chutes-mcp-server --self-check
Runs chutes_list_models with limit=1 against the live Chutes API over stdio transport. Prints OK + the first model id on success. This is the verification step that graduates read-only MCP tools out of BETA. Last passed live 2026-06-11 (via uvx from the local path).
For OpenAI-compat targets, the script prints a one-liner curl https://llm.chutes.ai/v1/models that the user can run themselves.
MCP tool surface
| Tool | Endpoint | Label |
|---|
chutes_list_models | GET https://llm.chutes.ai/v1/models | read |
chutes_chat_complete | POST https://llm.chutes.ai/v1/chat/completions (streaming) | read |
chutes_list_chutes | GET /chutes/ | read |
chutes_deploy_vllm | POST /chutes/vllm | [BETA] write |
chutes_deploy_diffusion | POST /chutes/diffusion | [BETA] write |
chutes_teeify | PUT /chutes/{id}/teeify | [BETA] write — endpoint GONE from openapi as of 2026-06-11; use tee=True at deploy time instead |
chutes_list_aliases | GET /model_aliases/ | read |
chutes_set_alias | POST /model_aliases/ | [BETA] write |
chutes_delete_alias | DELETE /model_aliases/{alias} | [BETA] write |
chutes_get_usage | GET /invocations/usage | read |
chutes_get_quota | GET /users/me/quotas | read |
chutes_get_discounts | GET /users/me/discounts | read |
chutes_get_evidence | GET /chutes/{id}/evidence?nonce=<64 hex chars> (nonce required; auto-generated) | read |
chutes_oauth_introspect | POST /idp/token/introspect | read |
chutes_list_api_keys | GET /api_keys/ | read |
chutes_create_api_key | POST /api_keys/ | [BETA] write |
Write tools prepend [BETA] to the tool description string so the MCP client shows the label in the tool picker.
Files in this skill
chutes-mcp-portability/
├── SKILL.md (this file)
├── references/
│ ├── mcp-tool-map.md endpoint → MCP tool mapping
│ ├── cursor-setup.md
│ ├── cline-setup.md
│ ├── aider-setup.md
│ └── openrouter-style.md
├── mcp-server/
│ ├── server.py FastMCP stdio server
│ └── pyproject.toml uv / pipx install manifest
└── scripts/
└── generate_agent_config.py per-target config emitter
Safety rules
- Never write a raw
cpk_ into a generated config file. Prefer env-var references (${CHUTES_API_KEY}) that the client resolves at runtime. If a target absolutely requires an inline key, warn loudly.
- MCP tools never return
cpk_ through results. The server reads the key at boot and uses it internally only.
- Write tools require BETA label. Do not remove the
[BETA] prefix from a write tool's description without a recorded verification run that exercised it.
- Health check is not optional. A skill completion without a successful health check stays BETA.
Related skills
chutes-ai (hub) — prerequisite credential setup.chutes-deploy [BETA] — write tools map 1:1 to deploy scripts; use the skill when the user wants an interactive walkthrough, use MCP when another agent needs programmatic access.chutes-sign-in [BETA] — chutes_oauth_introspect is the MCP-exposed form of the SIWC verify step.
