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.
https://mcp.ontrama.com/mcpPaste 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
- 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/mcpas 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:
claude mcp add --transport http trama https://mcp.ontrama.com/mcpThen 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:
{
"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.
{
"mcpServers": {
"trama": {
"url": "https://mcp.ontrama.com/mcp"
}
}
}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 invoices.read invoices.write agents.run |
What happens when a client connects for the first time:
- It calls
POST /mcpwithout a token and gets401with aWWW-Authenticateheader 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/authorizein your browser. You sign in, see what it asks for and approve. - It exchanges the code and its PKCE verifier at
POST /oauth2/tokenfor an access token (lxt_at_…, 7 days) and a refresh token that rotates on each use. - From then on it calls
POST /mcpwithAuthorization: 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.
{
"mcpServers": {
"trama": {
"url": "https://mcp.ontrama.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_PERSONAL_TOKEN"
}
}
}
}claude mcp add --transport http trama https://mcp.ontrama.com/mcp \
--header "Authorization: Bearer YOUR_PERSONAL_TOKEN"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.
boards.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).
boards.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.
boards.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.
boards.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).
boards.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.
invoices.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.
invoices.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.
agents.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.
run token- report_progress
- For Claude inside a run: posts a line of progress to the run on the task.
comments.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.
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.