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, comment, and read and write documents. Agents act as you, with exactly the access you have in the app.

On this page
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, invoices
Lifetime
7-day tokens the client refreshes

Personal token

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

Claude

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

Claude app (web and desktop)

  1. Open SettingsConnectors and choose Add custom connector.
  2. Name it Trama and paste https://mcp.ontrama.com/mcp as the URL.
  3. 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 URLPOSThttps://mcp.ontrama.com/mcp
Protected resource metadataGEThttps://mcp.ontrama.com/.well-known/oauth-protected-resource/mcp
Authorization serverhttps://api.ontrama.com
Client registrationDynamic (RFC 7591), public client, PKCE with S256
Scopesboards.read boards.write comments.write invoices.read invoices.write agents.run

What happens when a client connects for the first time:

  1. It calls POST /mcp without a token and gets 401 with a WWW-Authenticate header pointing at the protected-resource metadata.
  2. The metadata names the authorization server, https://api.ontrama.com; the client reads its /.well-known/oauth-authorization-server.
  3. It registers itself with POST /oauth2/register.
  4. It opens https://ontrama.com/oauth2/authorize in your browser. You sign in, see what it asks for and approve.
  5. 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.
  6. 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

The server has 53 tools, all built on API operations that OAuth tokens may use. Tools take ids, names, issue keys like ACME-42 or links; when a name could mean several things, the tool answers with the candidates instead of guessing. Agents search or list their tasks, read a task or the page that matters, then act; specs and decisions go into pages linked to their tasks.

Find and readboards.read
search
Tasks, documents, comments and boards you can see, with links to each.
list_my_tasks
Your open tasks across boards, most urgent first.
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, assignees 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, milestone, labels, assignees, sub-issues, relations, checklists, pull requests, time tracked, threaded comments and the pages that mention it.
list_milestones
A board's milestones with their target dates.
list_tags
A board's labels.
list_task_templates
A board's task templates.
list_task_pull_requests
The pull requests and merge requests linked to a task.
list_time_entries
Time tracked on a task, or across a board, milestone or person for a period (that view needs invoice access).
Read documentsboards.read
list_workspaces
Your workspaces with their boards and people (user ids for mentions).
list_documents
A workspace's page tree as links, with open threads, the last edit and which pages are restricted.
search_documents
Finds pages by title and text, with excerpts, in one workspace or across all of yours.
get_document
One page as Markdown, with its path, link, version, who can open it, sub-pages, the pages and tasks that mention it, and optionally its threads.
Change tasksboards.write
create_task
Creates a task in a column, with milestone, priority, template or parent, optionally after a given card.
create_task_from_template
Creates a task from one of the board's templates.
create_sub_issue
Adds a sub-issue under a task.
move_task
Moves a task to another column of its board, optionally after a given card.
update_task_metadata
Changes name, description, dates, priority, milestone and parent, and marks it done or not done.
set_task_assignees
Sets, adds or removes assignees by name, e-mail or “me”.
set_task_tags
Sets, adds or removes labels by name, creating missing ones as the app does.
add_task_relation
Links two tasks: blocks, blocked by, related or duplicate of.
remove_task_relation
Removes a link between two tasks.
add_checklist
Adds a checklist to a task, with items.
add_check_item
Adds items to a checklist.
set_check_item_done
Checks or unchecks a checklist item.
link_pull_request
Links a GitHub pull request or GitLab merge request to a task.
start_timer
Starts the task's timer (does nothing if it is already running).
stop_timer
Stops the task's timer.
Track timeboards.write
log_time
Logs time on a task: a duration like 1h30 on a day, or a start and end, with a note; yours or, for board admins, someone else’s.
update_time_entry
Changes the length, start, note or person of a time entry.
delete_time_entry
Deletes a time entry (time on a sent invoice stays locked).
Plan and writeboards.write
create_milestone
Creates a milestone on a board, with a target date.
update_milestone
Renames a milestone or changes its date or description.
create_document
Creates a page in a workspace, optionally under a parent page or private to you.
update_document
Renames a page, or replaces or appends to its body; never overwrites someone else’s newer edit.
Read invoicesinvoices.read
list_invoices
Invoices of the workspaces you administer, by status (overdue too), client or date, with what is still owed.
get_invoice
One invoice in full: lines, totals, payments, notes and its link.
Billinvoices.write
create_invoice
Drafts an invoice with the next number and your usual issuer and terms, from lines or from unbilled tracked time at an hourly rate.
update_invoice
Changes lines, client, dates, notes or terms, or takes a sent invoice back to draft.
mark_sent
Marks a draft as sent; its tracked time becomes billed.
record_payment
Records a payment; covering the total marks the invoice paid.
Delegate to Claudeagents.run
delegate_task
Sends a task to Claude Code in your repository's GitHub Actions: the board's repository or another, Auto or a chosen account, extra instructions. A pull request comes back.
get_agent_run
One run: its status, attempts and the accounts they used, progress, branch and pull request.
cancel_agent_run
Cancels a run that is queued, waiting for an account or going, and its GitHub run.
list_agent_runs
A task's runs with Claude, newest first.
Report from a runrun token
report_progress
For Claude inside a run: posts a line of progress to the run on the task.
Commentcomments.write
add_comment
Comments on a task or replies in a thread; mentions notify people.
add_document_comment
Starts a thread on a page, optionally quoting a passage, or replies to one.

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. Agents link tasks and documents in Markdown, as [ACME-12 Fix the login](/tasks/123) or [Release plan](/documents/45), and Trama shows the backlinks on both sides.

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.”
  • “Read the Release plan document and create a task for each open item in it.”
  • “Write a spec page for ACME-42 from its comments, link it to the task and add a checklist of the open items.”
  • “Create a milestone “Beta” for Nov 14 and put every high-priority task in To do on it.”
  • “Log 1h30 on ACME-42 for today, then draft an invoice to Globex with last month’s time on Website at $120 an hour.”

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. Invoice access is offered to people who administer a workspace, and connections made before it existed need connecting again to get it.

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.

See also