Tecto docs
tectoapp.io

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:read token 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 the configVersion the 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. Optional filters (field key, eq, ne, contains, is_empty or is_not_empty, or gt, gte, lt, lte on a number or a date, and a value such as an option label) and match (all or any) return only the matching cards, and the totals count only those. Archived cards are left out and only counted; archived (include or only) returns them. Each card carries its number, the #42 the 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. The configVersion from get_board guards 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_board checks 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 with archived: false. The card keeps its column, lane and position. With allBoards it 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_card takes the page id or the card number (42 for #42) and prints the number in its header. Another card pinned into the body is a basalt-card block, 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 a basalt-card block 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_card lists the card's open questions after the body, and get_my_work lists 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 with failed that it could not. get_my_work lists 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_automation also 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 HTTP PUT (curl --fail -T shot.png "<address>") and gets back the Markdown that embeds the file; it adds that to the card with update_card itself. 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_work to 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:read at all, a content:read token 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.