> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellistech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trellis MCP Server

> Install Trellis tools in any MCP-compatible client.

The Trellis MCP server lets external AI clients use Trellis tools through a standard MCP connection. Use the hosted Streamable HTTP endpoint when your client supports it, or the stdio bridge from the npm package when it does not.

## Hosted endpoint

```text theme={null}
https://api.trellistech.com/v1/mcp-server
Authorization: Bearer trls_...
```

Use this endpoint when your MCP client supports Streamable HTTP.

## Quick install

### Claude Code

```bash theme={null}
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:

```bash theme={null}
export TRELLIS_API_KEY=trls_...
claude mcp add --transport http --scope user \
  trellis https://api.trellistech.com/v1/mcp-server \
  --header "Authorization: Bearer $TRELLIS_API_KEY"
```

### Claude Desktop

Print the config snippet:

```bash theme={null}
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 Claude custom connector:

```text theme={null}
Settings: https://claude.ai/customize/connectors
Server URL: https://api.trellistech.com/v1/mcp-server
Credential: Trellis workspace API key, when prompted
```

Print the same instructions from the CLI:

```bash theme={null}
npx -y @trellistech/mcp-server print-config claude-hosted
```

### Cursor and Codex

Workspace admins can also connect from **Settings > Developer** in Trellis. The **Developer / API** section can create a workspace key and prepare setup instructions for Claude Code, Claude Desktop, Claude Cowork, Cursor, and Codex.

### Generic MCP clients

Prefer Streamable HTTP:

```text theme={null}
https://api.trellistech.com/v1/mcp-server
Authorization: Bearer trls_...
```

For stdio-only clients:

```json theme={null}
{
  "mcpServers": {
    "trellis": {
      "command": "npx",
      "args": ["-y", "@trellistech/mcp-server", "stdio"],
      "env": {
        "TRELLIS_API_KEY": "trls_...",
        "TRELLIS_MCP_URL": "https://api.trellistech.com/v1/mcp-server"
      }
    }
  }
}
```

Provide `TRELLIS_API_KEY` in the client environment before starting the stdio bridge.

## Workspace selection

Trellis API keys are workspace-scoped. Every MCP tool includes an optional `workspace_id` argument. Leave it empty to use the workspace this API key was issued for. If you provide it, it must match the key's scope; cross-workspace calls are rejected.

```json theme={null}
{
  "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 stops access there without affecting the others.

## Tool catalog

Use your MCP client's tool list or run:

```bash theme={null}
npx -y @trellistech/mcp-server doctor
```

The exposed catalog mirrors Trellis operational read tools and gated write tools across tasks, properties, reservations, conversations, workforce, knowledge base, and automations.

## Resources

The hosted endpoint also exposes read-only MCP resources:

| Resource URI                                  | Description                     |
| --------------------------------------------- | ------------------------------- |
| `trellis://agents/{agent_id}/profile`         | Agent profile and configuration |
| `trellis://agents/{agent_id}/memory`          | Recent agent memory             |
| `trellis://knowledge/documents/{document_id}` | Workspace knowledge documents   |
| `trellis://knowledge/skills/{document_id}`    | Agent-facing skills             |

Resources are scoped to the workspace API key. Use them when a client needs instructions, skills, or agent knowledge as context without calling a Trellis operation tool.

## Safety model

* Read tools work immediately after authentication.
* Write tools keep the same permission and confirmation behavior as Trellis.
* Messaging tools must 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 logged and returned to clients as typed JSON errors.
* The hosted endpoint applies basic per-key rate limiting.

## Example: Slack triage bot in 5 minutes

1. Add the Trellis MCP server to the AI client that powers your Slack bot.
2. Store `TRELLIS_API_KEY` in the bot runtime environment.
3. In your bot instructions, tell it to use Trellis tools for task lookup, task summaries, and task updates.
4. Require explicit confirmation before calling any tool that creates tasks, updates tasks, or sends messages.
5. Include `workspace_id` in tool calls when the bot serves more than one workspace.

## Troubleshooting

| Symptom                     | Fix                                                                   |
| --------------------------- | --------------------------------------------------------------------- |
| `Missing TRELLIS_API_KEY`   | Run the installer again or export the key.                            |
| `Unauthorized`              | Recreate the API key from **Settings > Developer**.                   |
| `Rate limit exceeded`       | Retry after a minute or reduce concurrent calls.                      |
| Tools appear but calls fail | Check that the user behind the key belongs to the selected workspace. |
| No tools listed             | Confirm the API key belongs to a Trellis user with workspace access.  |