Model Context Protocol

Trama for AI agents

Trama runs a hosted MCP server, so Claude, Cursor and other MCP clients can read your boards, create and move tasks and comment. Agents act as you, with exactly the access you have in the app.

On this page

How it works
Claude
Cursor
Other clients
Personal token
Tools
Troubleshooting

MCP server URL

https://mcp.ontrama.com/mcp

Paste the URL into your client with no headers. It opens Trama in your browser to sign in and approve the connection.

How it works

The server speaks Streamable HTTP. It stores nothing: every tool call becomes requests to the Trama API with your credentials, so the agent sees the boards you can see and can change only what you could change yourself. There are two ways to sign in.

OAuthRecommended

Setup: Paste the URL, approve in the browser
Access: Scoped: read, write, comment
Lifetime: 7-day tokens the client refreshes
Revoke: SettingsConnected apps

Personal token

Setup: Create a token, send it as a header
Access: Everything you can do in the app
Lifetime: Until you replace it
Revoke: SettingsAPI & MCP

Claude

Both connect with OAuth: add the URL once, then approve access in your browser.

Claude app (web and desktop)

Open SettingsConnectors and choose Add custom connector.
Name it Trama and paste https://mcp.ontrama.com/mcp as the URL.
Choose Connect. Trama opens to sign in; review the access and approve.

Then ask in a chat, for example “What's in progress on the Website board?” On team plans, an owner may need to add the connector for the organization first.

Claude Code

Add the server from your terminal:

Terminal

claude mcp add --transport http trama https://mcp.ontrama.com/mcp

Then run /mcp inside Claude Code, pick trama and sign in when the browser opens.

To share it with everyone working in a repository, put it in .mcp.json at the project root instead:

.mcp.json

{
  "mcpServers": {
    "trama": {
      "type": "http",
      "url": "https://mcp.ontrama.com/mcp"
    }
  }
}

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), or add it from Cursor's MCP settings. Cursor discovers OAuth on its own and opens your browser to approve.

~/.cursor/mcp.json

{
  "mcpServers": {
    "trama": {
      "url": "https://mcp.ontrama.com/mcp"
    }
  }
}

Moving from the old local server?

If your config still runs a local process (command, args and env with API keys), replace that block with the url above and restart Cursor. The hosted server is the supported setup.

Other clients

Any client that supports Streamable HTTP and OAuth discovery works with the URL alone. What it needs to know:

	Value
Server URL	POSThttps://mcp.ontrama.com/mcp
Protected resource metadata	GEThttps://mcp.ontrama.com/.well-known/oauth-protected-resource/mcp
Authorization server	https://api.ontrama.com
Client registration	Dynamic (RFC 7591), public client, PKCE with S256
Scopes	`boards.read` `boards.write` `comments.write`

What happens when a client connects for the first time:

It calls POST /mcp without a token and gets 401 with a WWW-Authenticate header pointing at the protected-resource metadata.
The metadata names the authorization server, https://api.ontrama.com; the client reads its /.well-known/oauth-authorization-server.
It registers itself with POST /oauth2/register.
It opens https://ontrama.com/oauth2/authorize in your browser. You sign in, see what it asks for and approve.
It exchanges the code and its PKCE verifier at POST /oauth2/token for an access token (lxt_at_…, 7 days) and a refresh token that rotates on each use.
From then on it calls POST /mcp with Authorization: Bearer lxt_at_….

The server is stateless and answers POST only; GET and DELETE on /mcp return 405.

Personal token

For clients that can't do OAuth. Create a token in SettingsAPI & MCP and send it as a Bearer token. The server splits it into your API key and secret before calling the API.

mcp.json

{
  "mcpServers": {
    "trama": {
      "url": "https://mcp.ontrama.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_TOKEN"
      }
    }
  }
}

Claude Code

claude mcp add --transport http trama https://mcp.ontrama.com/mcp \
  --header "Authorization: Bearer YOUR_PERSONAL_TOKEN"

Treat it like a password

The token isn't scoped: it can do everything you can, on every board you can reach, and it doesn't expire. It is shown once. Replacing it cuts off every client that uses the old one; OAuth connections keep working.

Tools

Eleven tools, all built on API operations that OAuth tokens may use. Agents chain them: find the board, take a snapshot, then act on a task by id or issue key.

Readboards.read

find_board_by_name: Finds a board by (part of) its name and returns its id.
get_board_snapshot: Columns and their cards (titles, labels and dates), without descriptions.
find_column_by_name: Finds a column on a board, for the id that creating and moving need.
find_task_by_issue_key: Opens a task by its key, like ACME-42.
find_task_by_name: The first task on a board whose name matches.
search_tasks_by_name: Every task on a board whose name matches, with its column.
get_task_detail: One task in full: description, comments, checklists and attachments.

Writeboards.write

create_task: Creates a task in a column, optionally from a template, as a sub-issue or after a given card.
move_task: Moves a task to another column of its board, optionally after a given card.
update_task_metadata: Changes name, description, dates, priority, parent, labels and assignees, and adds blocks, blocked-by, related or duplicate links.

Commentcomments.write

add_comment: Comments on a task; @username mentions notify people.

update_task_metadata also reads the task back, so it needs boards.read as well. Relations it adds are append-only; a duplicate link can be removed by passing duplicate_of: null.

Things to ask

“Summarize what's overdue on the Website board.”
“Create a task in To do on Website: update the pricing page, due Friday, high priority.”
“Move ACME-42 to Done and comment that it shipped in 2.4.”

Troubleshooting

Tools fail with 401 Unauthorized

With OAuth, finish the browser approval and check that the client saved the connection; reconnecting starts it over. With a personal token, send Authorization: Bearer KEY.SECRET exactly as copied, and copy it again if it was replaced.

A tool fails with 403 missing_scope

The connection was approved without that scope. Remove the app in SettingsConnected apps and connect again, approving read, write and comment access.

The agent says a board or task doesn’t exist

The API answers 404 for anything you can't see, so the agent can't tell missing from private. Check that your account can open the board in Trama.

Which boards can the agent see?

The same ones you can, no more. OAuth scopes narrow what it may do; they never add access your role doesn't have.

How do I disconnect a client?

OAuth clients: SettingsConnected apps, then revoke. Clients using the personal token: replace the token in SettingsAPI & MCP.