MCP server

Tekk exposes a Model Context Protocol (MCP) server so you can work with your board from inside the coding agent you already use — Claude Code, Codex, Cursor, or any MCP-capable client. Read and write specs, launch a fleet of parallel sessions, review Tekk’s proposals, and read the workspace’s context without leaving the terminal.

Each connection is bound to one workspace, fixed by the URL you connect with and your membership — so no tool ever asks which workspace to use.

Install in Claude Code

The quickest way is the Tekk plugin, which connects this server and installs the four skills that drive your board — sweep, blitz, triage and spec:

/plugin marketplace add guccikudo92615/tekk-skills
/plugin install tekk@tekk

That is the whole setup: the plugin declares the MCP server, so there is no separate connect step and nothing to paste into your own config. See Loops and their skills for what the four do.

The rest of this page is the manual path — for pinning one workspace, for other clients, and for CI.

Connect the server on its own

Grab your workspace URL from Settings → API keys in the app (it looks like https://app.tekk.coach/api/mcp/<workspace-slug>), then:

claude mcp add --transport http tekk https://app.tekk.coach/api/mcp/<workspace-slug>

No token, no header, nothing to paste. Then authenticate:

claude mcp login tekk

Your browser opens Tekk’s consent screen; approve it and you’re connected. Inside a running session you can do the same from the /mcp panel — pick tekk → Authenticate. Claude Code handles discovery, client registration and PKCE for you, and stores a short-lived, revocable token — never a key.

Check it worked with claude mcp list, or /mcp in a session — you should see tekk connected with its tools.

Add --scope user to the command to make Tekk available in every project on your machine instead of just the current one. Use --scope project to commit the server to .mcp.json for the whole team — safe here, because with OAuth there’s no secret in the file.

Re-authenticate any time with claude mcp login tekk; claude mcp logout tekk clears the local token. To cut a client off from Tekk’s side, use Settings → Connected apps.

Your teammates connect the same way

The workspace URL isn’t a secret and it isn’t personal — it’s the same URL for everyone. Each teammate runs the same two commands and approves the consent screen with their own Tekk account, and their actions land on the board under their own name. Nothing is shared, and there’s no per-seat setup: invite them to the workspace and their access starts on their next request (and stops the moment you remove them).

Other clients

• claude.ai custom connectors — paste the same workspace URL and approve in the browser.
• Cursor, VS Code, Zed, and other OAuth-capable MCP clients — point them at the workspace URL as a Streamable HTTP server; they’ll run the same browser flow.
• Anything else — see API key below.

The skills, outside Claude Code

Only Claude Code has plugins, so everywhere else the four skills install on their own and you connect the server separately (above):

npx skills add guccikudo92615/tekk-skills -a codex

Swap -a codex for -a cursor or any other agent the installer supports. The skills land in .agents/skills/, which those agents read, and they are the same files the Claude Code plugin ships.

With an API key

For CI, scripts, and clients that don’t do OAuth. The key is a bearer secret — treat it like a password.

1. In Settings → API keys, create a key. It’s scoped to the current workspace and shown once.
2. Put it in an environment variable, then reference it so it’s expanded at runtime and never written to a file in plaintext.

Claude Code — single-quote the header so the literal ${TEKK_API_KEY} placeholder is stored in your config and expanded from the environment at runtime:

export TEKK_API_KEY=tekk_...
claude mcp add --transport http tekk https://app.tekk.coach/api/mcp \
  --header 'Authorization: Bearer ${TEKK_API_KEY}'

Use single quotes. Double quotes let your shell expand the variable at add-time and bake the real key into the config file — exactly what you’re trying to avoid.

Codex (~/.codex/config.toml) — reads the key from the environment, so nothing sensitive is written to the file:

[mcp_servers.tekk]
url = "https://app.tekk.coach/api/mcp"
bearer_token_env_var = "TEKK_API_KEY"

Any other MCP client — point it at https://app.tekk.coach/api/mcp with an Authorization: Bearer tekk_... header, sourced from an environment variable wherever the client allows it.

A key carries its own workspace, so the bare /api/mcp URL is enough — and a key never grants a choice of workspace: on a workspace URL it must match the workspace in the path.

Never commit .mcp.json (or any file containing the key) to version control. If a key is ever exposed, revoke it in Settings → API keys — revocation takes effect on the next request.

Give your agent the workflow

The tools are only half of it — your agent works far better if it knows how to use them.

If you installed the plugin or the skills, you already have this and can skip the rest of this section: sweep, blitz, triage and spec carry the workflow, and they update when we improve them.

Only if you are on neither, paste this into your repo’s CLAUDE.md or AGENTS.md. Note that a pasted copy is frozen — it will not improve as Tekk does:

## Tekk (MCP: tekk)

Tekk runs autonomous loops over this project's codebase, raises what
they find as proposals, and keeps the spec board. The MCP is
connected to ONE workspace, fixed by the connection: never ask which.

Two slash commands carry most of the work, in this order:
- `/mcp__tekk__sweep` — work the WHOLE pending proposal inbox in one pass:
  re-check every finding against the code as it is now, say which no longer
  hold and why, then accept the survivors in a single batch.
- `/mcp__tekk__blitz` — turn the resulting specs into running coding
  sessions, as many at once as is collision-safe.

Workflow:
- Start with `get_workspace_overview`. Its `drift` block lists specs whose
  status disagrees with what actually merged — believe drift over a bare
  status.
- "What should I work on?" → `list_specs`, then `get_spec` for the full body
  and acceptance criteria before implementing. `get_spec` embeds `linkedPrs`,
  `checklistProgress` and a `drift` verdict.
- `update_spec_status` → in-progress the moment you start. Keeping status
  current is part of the work, not a separate step.
- Closing a spec from a PR is two things, both yours: tick the
  `## Build order` items you finished (`update_spec`), and put `Closes TEK-n`
  in the PR body. A PR that merely MENTIONS a spec links it for display and
  moves nothing.
- New work found mid-session → `create_spec`. Research the code first: the
  tool requires load-bearing claims to carry real locators (file:line, a URL,
  a measurement) before it accepts the spec. A feature with independently
  buildable parts becomes a parent plus one Sub-task per part (`parentSpec`),
  each with its own `touches` and `dependsOn`.
- Proposals — what the loops raised, awaiting a decision. `list_proposals`
  (each row carries `loopSkill`, the loop that raised it, and `evidenceCheck`,
  the last verdict on its evidence); `get_proposal` to read one in full;
  `verify_proposal` to re-check its evidence against the CURRENT checkout;
  `revise_proposal` to have Tekk redraft it in place from your feedback;
  `decide_proposals` to accept or reject many in one call, or
  `accept_proposal` / `reject_proposal` for one. Always give a reason when
  rejecting — reasons steer the loops.
- Running work in parallel → `plan_batch` for a collision-free batch, then
  `start_session` for each session you open. `fleet_status` is the one-read
  picture; `update_session` marks one blocked or abandoned. Never claim a
  session completed — completion is derived from the spec's merged closing PR.
- Loops → `list_loops` (what is enabled and with how much rope), `list_runs`
  and `get_run` (what ran, what it cost, how its finding was verified),
  `run_loop` to fire one on demand.
- `list_documents` / `read_document` expose the workspace knowledge Tekk
  reasons from (product, audience, business model). Read before making
  product-level decisions.

What the tools do

Area	Tools	What you can do
Orientation	get_workspace_overview	Get your bearings — projects, open counts, and any specs whose status disagrees with what merged.
Specs	list_specs, get_spec, create_spec, update_spec, update_spec_status	Read the board, open a spec’s full body + acceptance criteria, add new work, and move specs todo → in-progress → completed.
Structure	add_dependency, remove_dependency	Declare that one spec must finish before another can start — a hard gate the batch planner respects.
Epics	list_epics, create_epic, archive_epic	Group several independent features under an epic, and retire one when it’s done.
Parallel execution	plan_batch, dispatch_batch, start_session, update_session, list_sessions, fleet_status	Plan a collision-free batch of specs to run at once, launch them, and track the fleet honestly.
Proposals	list_proposals, get_proposal, verify_proposal, revise_proposal, accept_proposal, reject_proposal, decide_proposals	See what Tekk is suggesting and which loop raised it, re-check a finding against your current code, have Tekk redraft one from your feedback, and decide a whole batch in a single call.
Loops	list_loops, list_runs, get_run, run_loop, set_loop, configure_loop, configure_workspace_loops	See which loops are on and how much rope they have, read what a run cost and how its finding was verified, fire one on demand, and set autonomy or the nightly run hour.
Code index	get_index_status, queue_reindex	Check what the loops can actually see — per-repo index freshness and coverage — and re-index one that has fallen behind.
Context	list_documents, read_document	Read the workspace knowledge — product, audience, business model — that Tekk reasons from.

There are also two slash commands in Claude Code, and they run in order.

/mcp__tekk__sweep works your whole pending proposal inbox in one pass. Findings pile up precisely because deciding them one at a time is never worth it — so sweep re-checks every one against the code as it is now, and separates the two things a stale finding can mean: it was fixed (reject), or the code merely moved (revise — the finding may still be entirely true and just cite the wrong lines). Those need opposite answers, and a refactor is not a fix. It reports, waits for your go, then takes the whole batch through one call.

/mcp__tekk__blitz turns the result into running work. It reads what your loops raised alongside your open specs, works out the biggest collision-safe batch, and opens a coding session per spec — using a tool that starts a session where your setup has one, falling back to a one-click task card, and to a paste-ready prompt in a plain terminal. Everything it opens is registered as a Session, so it shows up in fleet_status beside the rest of the fleet.

Neither command decides a proposal or launches anything without an explicit yes from you.

A few things are deliberate:

• The vocabulary is spec, not task/issue/ticket — see Core concepts.
• Verifying is a fact; deciding is a judgement. Re-checking a proposal’s evidence against your code writes freely. Accepting, rejecting and revising it need your explicit yes — an agent never decides one on your behalf.
• Goals are set in the app, not over MCP. The board is the agent’s surface; direction is yours.
• No tool takes a workspace argument. The connection decides.

Running work in parallel

The board isn’t just a list — it carries enough structure for an agent to safely run several specs at once:

• Sub-tasks, not scattered siblings. A feature that decomposes becomes a parent spec with one Sub-task per independently-buildable part (create_spec with parentSpec). Each child carries its own PR; the parent completes automatically when its children do.
• touches declares the code area a spec will modify, as globs. plan_batch refuses to co-schedule two specs whose areas overlap — they go in different waves instead of colliding in the same files.
• dependsOn is a hard gate. A spec waiting on a prerequisite isn’t dispatch-eligible until that prerequisite is genuinely finished.
• plan_batch picks the next safe set and returns a ready-to-launch kickoff package per spec. Scope it to one wave with parentSpec or epic. fleet_status then answers “what are my agents doing, and what’s left to launch?”
• Completion is derived, never claimed. A session is complete when the spec’s closing PR merges — so list_sessions shows what actually shipped rather than what an agent said it did.

Security & credentials

The agent surface is built to be safe to connect. What that means in practice:

• Prefer OAuth. It stores a revocable token instead of a long-lived secret, gates the first connection behind a consent screen, and each connected app is individually revocable under Settings → Connected apps.
• API keys are bearer secrets. They’re hashed at rest on our side and scoped to a single workspace — but on your machine, the key is only as safe as the file or environment holding it. Keep it in an environment variable, never inline in a committed file (see the key setup above).
• Give each person their own credential. A key binds one person to one workspace, so a shared key files everyone’s work under one name. Keys also die with membership: remove someone from the workspace and their key stops working on the next request.
• Revocation is immediate. The server is stateless — a fresh instance per request — so revoking a key or an OAuth grant cuts access on the very next call.
• Approve only connections you started. Because any app can self-register an OAuth client (even under a lookalike name), our consent screen shows the real destination host rather than the app’s chosen name, and warns you to approve only if you initiated the connection yourself.
• One grant, your whole account. An approved OAuth grant can act in any workspace your account belongs to — the workspace is fixed by the URL you connect with, but the grant follows your membership. Revoking the app under Settings → Connected apps severs it everywhere at once.
• Rate limit. Each credential gets its own budget of 120 requests per minute — generous for an interactive session, and one busy teammate never eats another’s.

How it fits the rest of Tekk

The MCP server is the terminal-side view of the same board the loops feed into. A loop notices something and drafts a proposal; you accept it and it becomes a spec; you (or your agent, over MCP) implement it and mark it done. Same board, two surfaces.