MCP server
Tecto ships a first-party MCP server, so an agent (Claude, an agent CLI, anything that speaks the protocol) can read and move a workspace's boards without anyone writing glue code.
There is nothing to install. The server runs on your Tecto instance and answers
at https://app.tectoapp.io/mcp; you point an agent at that address and give
it a token.
It is a thin layer over the public API: the endpoint holds no permission logic of its own but makes ordinary API requests with your credential, so an agent sees and changes exactly what you can. Card bodies cross the wire as canonical Markdown.
Setting it up
Mint a token first: Settings → Tokens, in the workspace the agent should
work in. Give it content:read if the agent should only read, content:write
if it should also write. The secret is shown once.
A token minted here works here: it reads and writes what Tecto shows you, and nothing the other apps hold. That also means you do not have to tell the agent which workspace to use: the token names one, and the endpoint reads it from there.
In an MCP host's configuration file:
{
"mcpServers": {
"tecto": {
"type": "http",
"url": "https://app.tectoapp.io/mcp",
"headers": {
"Authorization": "Bearer tecto_pat_…"
}
}
}
}
Hosts differ in how they spell this; what they all need is the address and the
Authorization header. In Claude Code, for example:
claude mcp add --transport http tecto https://app.tectoapp.io/mcp \
--header "Authorization: Bearer tecto_pat_…"
If your account is in several workspaces and you want to name one explicitly,
address https://app.tectoapp.io/mcp/w/<workspace id> instead. A token may
only ever name its own workspace, so the two have to agree.
Keeping an agent read-only is the token's job, not a setting: a
content:read token is refused by the server on every write, which is a
stronger guarantee than a switch on the client side.
Adding it as a connector
Hosts that offer no header field (claude.ai among them) add the endpoint as
a connector and sign you in instead. Paste the same address,
https://app.tectoapp.io/mcp, into the connector dialog; the rest is a sign-in and one
screen asking whether you want to connect. Nothing to copy, no token to keep.
A connector is broader than a token, and the screen says so before you agree:
- It covers every workspace you are a member of, not one.
- It reads and writes what you can. There is no read-only connector; mint
a
content:readtoken for an agent that should only look. - It still sees Tecto only, and it stops working when your access does.
Because a connector covers several workspaces, the agent says which one each call
means. It gets one more tool, list_workspaces, and every other tool takes the id of a
workspace as workspace, with no default: an agent that does not know which one you mean
asks you. Every answer except the list starts with the workspace it acted in. To keep a connector in one
workspace, add https://app.tectoapp.io/mcp/w/<workspace id> instead.
What the agent gets
Read-only unless marked.
get_workspace: name and shape of the workspace the token opens.list_boards/get_board: the boards, and one board's title, icon, columns and lanes, with theconfigVersionthe structure tools need.get_board_cards: a board's cards, grouped by column × lane, with honest per-group totals and cursors for the long columns. Optionalfilters(field key,eq,ne,contains,is_emptyoris_not_empty, orgt,gte,lt,lteon a number or a date, and a value such as an option label) andmatch(allorany) return only the matching cards, and the totals count only those. Archived cards are left out and only counted;archived(includeoronly) returns them. Each card carries itsnumber, the#42the app shows.create_board(write): a new board in a collection, with the default columns the app would seed, and optionally lanes.update_board(write): rename a board, set or remove its icon.update_board_columns/update_board_lanes(write): add, rename, reorder and remove columns or lanes in one step. TheconfigVersionfromget_boardguards the write: if the board changed since, nothing is written. Removing a column or lane that still has cards is refused unless the call says where they go (moveCardsTo) or accepts that they are unplaced (unplaceCards). Card pages are never deleted. A name another column or lane of the board already has is refused, as is a lane named like the row without a lane;create_boardchecks its names before the board exists.add_card(write): a new card at a column's end, or an existing page attached as a card.move_card(write): column, lane and position in one step, the same transactional move the app performs.archive_card(write) - archive a card on a board, or bring it back witharchived: false. The card keeps its column, lane and position. WithallBoardsit is archived on every other board it sits on as well, where the token may edit; bringing it back applies to the one board.get_card/update_card(write): a card's body as canonical Markdown, read and replaced whole.get_cardtakes the page id or the card number (42for#42) and prints the number in its header. Another card pinned into the body is abasalt-cardblock, as in the board text. Text the write leaves unchanged keeps its comments; only a comment on text the write deletes is detached.get_board_text/update_board_text(write): the text "About this board" as canonical Markdown, read and replaced whole, with the same version check as a card. A card pinned into the text is abasalt-cardblock and stays pinned as long as the block is kept.comment_on_card(write) /list_card_comments: the card's discussion.ask_on_card(write) /list_card_questions/withdraw_question(write): a question with two to six options that someone answers on the card with one click (see Questions on a card). An option can move the card to a column.get_cardlists the card's open questions after the body, andget_my_worklists the answers to your own questions from the last 14 days. Answering is done in the app, not by the agent.list_card_chat/reply_in_card_chat(write): the chat on a card with its agent (see Chat with the agent of a card). Only the card's agent replies, to a waiting message with its id, or says withfailedthat it could not.get_my_worklists the messages that wait for you.list_automations/list_automation_runs- a board's automations, with schedule, card template, target column and lane, status and next run, and what each rule did lately.create_automation/update_automation(write) - a rule that creates a card from a template on a schedule (daily, weekly or monthly, at a time in a named zone).update_automationalso pauses and resumes a rule and changes single parts of its template.run_automation(write) - run a rule once, now. The answer says whether it created a card, skipped (the previous card is not done) or paused itself (its column is gone).delete_automation(write) - remove a rule; the cards it created stay.prepare_attachment_upload(write): a single-use address (15 minutes, up to 25 MiB) to attach one file, such as a screenshot or a short video, to a card. The agent sends the bytes there with an HTTPPUT(curl --fail -T shot.png "<address>") and gets back the Markdown that embeds the file; it adds that to the card withupdate_carditself. Images show inline, other files as a link.search: full-text over the workspace; every hit says what it is.get_my_work- who the token acts as (a person, or a bot and whose bot), the cards whose person fields name it, with board, column and lane, and its unread mentions.
Giving an agent its own identity
An agent that works with your token acts as you: its comments and edits carry your name, and it cannot tell the cards meant for it from yours. A bot fixes both. Create one under Settings → Tokens → Bots, then mint a token for the bot there and give the agent that token instead of yours.
- Everything the bot does shows its name with "(bot, owned by …)". Give it a profile picture under Settings → Tokens → Bots with Upload picture….
- A bot is a member like any other: put it in a person field or mention it to
hand it a card. It calls
get_my_workto find what it was given. - A bot never has more rights than the person who owns it, and it takes no seat on the plan. When its owner leaves the workspace, its tokens stop working.
What the agent cannot do, the token could not do either: permissions, visibility and trash semantics are the server's, not the MCP layer's.
When something is refused
The endpoint answers the way the API does, so a refusal says which of three things happened:
- 401: no credential, or one that is unknown, revoked or expired.
- 403: a credential that may not do this: a token without
content:readat all, acontent:readtoken asked to write, or one belonging to a different workspace than the address names. - Everything else is the ordinary API's answer, passed through with the server's own wording.