Motir
Sign inStart free

The Motir MCP server

Motir's project plan is reachable by any Model Context Protocol client over one endpoint. Point your agent at it with a personal access token and it can read the ready set, claim the next item, create work, move statuses and comment — through the same services, permissions and data the web app uses.

Should you use this, or the REST API?

Motir publishes two programmatic surfaces over the same domain. They are not alternatives with the same trade-off, and the difference is worth thirty seconds before you pick.

Endpoint
The MCP server
POST /api/mcp
The REST API
/api/v1/…
Built for
The MCP server
An agent you control — it reads tool descriptions at run time.
The REST API
A client you ship — code written once against a fixed shape.
Stability
The MCP server
Expected to change. Rewording a description or renaming an argument is how an agent’s behaviour gets tuned.
The REST API
Additive only. A breaking change mints /api/v2; v1 keeps its promise.
Shape
The MCP server
The same. MCP payloads are derived from the v1 response schemas, so the two describe provably identical objects.
The REST API
The same, and it is the source the MCP derives from.
Auth
The MCP server
One personal access token, one scope set.
The REST API
The same credential works on both.
Wiring an agent? Stay here. Writing software other people install? The REST API is the other half — it is the one that promises not to change under you.

Read the API reference

1Mint a token

In the app: Settings → Account → Tokens → Create. Give it a label and an expiry. The plaintext is shown once — copy it then; Motir keeps only a hash.

2Point your client at the endpoint

Every client needs the same four facts. They are Motir’s, they are the same for every agent, and everything below this table is one of them transcribed into a vendor’s file format.

URL
https://app.motir.co/api/mcp
Transport
Streamable HTTP — not SSE, and not a stdio command
Header
Authorization: Bearer <token>, on every request
Token
motir_pat_<your-token> — the one you minted in step 1
Don’t paste the token into a file your repository tracks. Where your client can read it from somewhere else, the block below does that instead.

Claude Code

.mcp.json
{
  "mcpServers": {
    "motir": {
      "type": "http",
      "url": "https://app.motir.co/api/mcp",
      "headers": { "Authorization": "Bearer motir_pat_<your-token>" }
    }
  }
}

Or one command: claude mcp add --transport http motir https://app.motir.co/api/mcp --header "Authorization: Bearer motir_pat_<your-token>" · Claude Code documentation · format checked 2026-08-06

Cursor

~/.cursor/mcp.json — or .cursor/mcp.json for one project
{
  "mcpServers": {
    "motir": {
      "url": "https://app.motir.co/api/mcp",
      "headers": { "Authorization": "Bearer ${env:MOTIR_TOKEN}" }
    }
  }
}

Cursor interpolates ${env:…}, so the token stays in your environment and out of the file. · Cursor documentation · format checked 2026-08-06

VS Code

.vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "motir-token",
      "description": "Motir personal access token",
      "password": true
    }
  ],
  "servers": {
    "motir": {
      "type": "http",
      "url": "https://app.motir.co/api/mcp",
      "headers": { "Authorization": "Bearer ${input:motir-token}" }
    }
  }
}

VS Code prompts for the token the first time the server starts and stores it securely — nothing secret is written to the file. · VS Code documentation · format checked 2026-08-06

Codex CLI

~/.codex/config.toml
[mcp_servers.motir]
url = "https://app.motir.co/api/mcp"
bearer_token_env_var = "MOTIR_TOKEN"

bearer_token_env_var takes the variable’s name, not the token. · Codex CLI documentation · format checked 2026-08-06

Any other streamable-HTTP client

whatever your client calls its config
Transport:  streamable HTTP
URL:        https://app.motir.co/api/mcp
Header:     Authorization: Bearer motir_pat_<your-token>

Windsurf, Zed, Cline, Goose, or something you wrote yourself — the same four facts under different key names. · Any other streamable-HTTP client documentation · format checked 2026-08-06

3Check it

Call whoami. It takes no arguments and answers with the user the token belongs to, the workspace it is bound to, and the scopes it was granted — so one call confirms all three at once.

A 401 means the token is absent, malformed, unknown, revoked or expired — the five are deliberately not distinguished, so a caller cannot probe token state. Mint a fresh one and try again.

What your token can call

Scope
project:browse
What it gates
Open the project and read its work items, boards, backlog and reports.
Scope
lesson:view
What it gates
Read what the project's AI planner learned from its own planning work.
Scope
lesson:manage
What it gates
Retire a lesson or add one — both change the standing instructions the planner is given.
Scope
lesson:reinforce
What it gates
Note that a lesson's mistake happened again. It changes nothing the lesson says.
Scope
work_item:edit
What it gates
Create, update, assign and move work items, and transition them on the board.
Scope
work_item:archive
What it gates
Archive a work item and restore it later. Affects that item only — its children stay.
Scope
work_item:delete
What it gates
Permanently delete a work item and everything beneath it. Cannot be undone.
off by default
Scope
comment:add
What it gates
Post comments on work items, and edit or delete your own.
Scope
sprint:manage
What it gates
Start and complete Sprints, and rank the backlog.
Scope
ai:plan
What it gates
Submit a planning job that spends the workspace’s AI credits and proposes plan changes.
Scope
ai:view_plan
What it gates
Add proposals to a generated plan and close it for review. Reading a plan needs only project access.
Scope
ai:decide_plan
What it gates
Turn a plan’s proposals into real work items, or end the plan without creating any.

What next

MCP tools — all 55 tools, what each does, and the scope that gates it. Read the full reference