Trellis MCP Server

@trellistech/mcp-server gives MCP clients first-class access to Trellis operations tools.

It supports two paths:

• Streamable HTTP to the hosted Trellis MCP endpoint: https://trellis-api.fly.dev/v1/mcp-server
• stdio bridge for clients that do not support Streamable HTTP yet

60-second install

Claude Code

npx -y @trellistech/mcp-server install claude-code

The installer prompts once for TRELLIS_API_KEY, stores it in ~/.trellis/mcp.env, and registers the hosted Streamable HTTP endpoint with Claude Code.

Manual equivalent:

export TRELLIS_API_KEY=trls_...
claude mcp add --transport http --scope user \
  trellis https://trellis-api.fly.dev/v1/mcp-server \
  --header "Authorization: Bearer $TRELLIS_API_KEY"

Claude Desktop

Print the config snippet:

npx -y @trellistech/mcp-server print-config claude-desktop

Add the output to mcp.json and set TRELLIS_API_KEY in your shell or launcher environment.

Claude Cowork

Use the hosted endpoint as a custom Streamable HTTP MCP integration:

URL: https://trellis-api.fly.dev/v1/mcp-server
Header: Authorization: Bearer ${TRELLIS_API_KEY}

If Cowork marketplace registration is available for your workspace, use the Trellis marketplace integration instead. It points to the same endpoint and uses the same API key permissions.

Generic MCP client

Use Streamable HTTP when the client supports it:

https://trellis-api.fly.dev/v1/mcp-server
Authorization: Bearer trls_...

Use stdio when it does not:

{
  "mcpServers": {
    "trellis": {
      "command": "npx",
      "args": ["-y", "@trellistech/mcp-server", "stdio"],
      "env": {
        "TRELLIS_API_KEY": "trls_...",
        "TRELLIS_MCP_URL": "https://trellis-api.fly.dev/v1/mcp-server"
      }
    }
  }
}

Authentication

Create an API key from Trellis workspace settings, then run:

npx -y @trellistech/mcp-server install claude-code

The key is saved to ~/.trellis/mcp.env with file mode 0600. The stdio bridge reads TRELLIS_API_KEY from the environment first, then falls back to that file.

OAuth is planned for a future minor version. API keys are the stable auth mechanism for 0.x.

Workspace selection

Trellis API keys are workspace-scoped. Every exposed Trellis tool accepts an optional workspace_id parameter. Leave it blank to use the workspace this key was issued for. If you provide it, it must match the key's scope — cross-workspace calls are rejected with a typed error pointing you at issuing a separate key per workspace.

Example tool argument:

{
  "workspace_id": "haven-vacation-rentals",
  "limit": 10
}

To operate on multiple workspaces, issue one API key per workspace and connect each as a separate MCP server (e.g., trellis-haven, trellis-renjoy). Revoking a key in one workspace then immediately stops access there without affecting the others.

Safety model

• Read tools work immediately after authentication.
• Write tools keep the same permission and confirmation behavior as Trellis.
• Messaging tools must still show the payload and wait for explicit confirmation before sending.
• The server logs every tool call with workspace_id, user_id, and tool_name.
• Failures are reported to Sentry with the same tags and returned to clients as typed JSON errors.
• The hosted endpoint applies basic per-key rate limiting and request timeouts.

Extending the package

This package is intentionally small:

• src/config.mjs builds client-specific install commands and config snippets.
• src/stdio.mjs implements MCP stdio framing and forwards JSON-RPC to the hosted endpoint.
• src/cli.mjs wires the installer, config printer, doctor, and stdio bridge.

To fork for workspace-specific tools, keep the stdio bridge and point TRELLIS_MCP_URL at your own MCP-compatible HTTP server, or wrap proxyJsonRpcMessage() to intercept custom tools before forwarding the rest to Trellis.

Troubleshooting

Run:

npx -y @trellistech/mcp-server doctor

Common failures:

| Symptom | Fix | | --- | --- | | Missing TRELLIS_API_KEY | Run the installer again or export TRELLIS_API_KEY. | | Unauthorized | Revoke and recreate the Trellis API key. | | Trellis MCP upstream returned 429 | Slow down the client or retry after a minute. | | No tools listed | Confirm the API key belongs to a Trellis user with workspace access. |

Versioning

0.x is the integration-hardening line. Public CLI commands and environment variables follow semver once the package reaches 1.0.0.