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. List and implement specs, review Tekk’s proposals, and read the workspace’s context without leaving the terminal.

The server speaks MCP over Streamable HTTP at:

https://app.tekk.coach/api/mcp

Each connection is bound to one workspace (fixed by your credentials), so no tool ever asks which workspace to use.

Connect

Two ways to authenticate. We recommend OAuth — it stores a short-lived, revocable token instead of a long-lived secret on disk, gates the first connection behind a consent screen, and lets you revoke each connected app individually. Use an API key for headless clients (CI, scripts) or clients that don’t support OAuth.

With OAuth (recommended)

Works with current Claude Code and claude.ai custom connectors — no key to paste or store.

1. In Tekk, go to Settings → API keys and copy your workspace URL:

   https://app.tekk.coach/api/mcp/<workspace-slug>

2. Add the server with no auth header — Claude Code:

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

3. Authenticate: run /mcp inside Claude Code (or claude mcp login tekk) and approve access on the Tekk consent screen in your browser. Claude Code handles discovery, client registration, and PKCE automatically, then stores a revocable token — not your key.

Re-authenticate anytime from the /mcp panel (or claude mcp login tekk); disconnect locally with claude mcp logout tekk. To revoke from Tekk’s side, use Settings → Connected apps. For claude.ai custom connectors, paste the same workspace URL and approve in the browser.

The workspace is pinned by the URL, and your membership is re-checked on every request.

With an API key

For CI, scripts, and clients without 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.

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 (recommended)

The tools are only half of it — your agent works far better if it knows how to use them. Paste this into your repo’s CLAUDE.md or AGENTS.md:

## Tekk (MCP: tekk)

Tekk is this project's AI CTO — it maintains the spec board, runs autonomous
improvement loops, and proposes work. The MCP is connected to ONE workspace.

Workflow:
- Start sessions with `get_workspace_overview` to orient (projects, counts).
- "What should I work on?" → `list_specs` (open work), then `get_spec` for the
  full body + acceptance criteria before implementing.
- When you start implementing a spec, `update_spec_status` → in-progress;
  when the work has shipped, → completed.
- New work discovered mid-session → `create_spec` (type: feature | problem |
  technical | research | improvement). Write real acceptance criteria.
- `list_proposals` shows Tekk's own suggestions awaiting a decision. Read one
  fully (`get_proposal`) before deciding. Accepting creates a spec; rejecting
  with a `reason` steers future proposals — always give a reason.
- `list_documents` / `read_document` expose the workspace knowledge Tekk
  reasons from. Read before making product-level decisions.
- Goals are read-only here (`list_goals`) — set and steer goals in the app.

The workspace is fixed by the API key: never ask which workspace to use.

What the tools do

The server exposes a focused set of tools, grouped by what they touch:

Area	Tools	What you can do
Orientation	get_workspace_overview	Get your bearings — projects and counts.
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 through their states.
Proposals	list_proposals, get_proposal, accept_proposal, reject_proposal	See what Tekk is suggesting, read one in full, then accept (creates a spec) or reject with a reason.
Epics	list_epics, create_epic	Group related specs under an epic.
Context	list_documents, read_document	Read the workspace knowledge — product, audience, business model — that Tekk reasons from.
Goals	list_goals	Read active goals. Goals are set and steered in the app, so they’re read-only here.

A few things are deliberate:

• The vocabulary is spec, not task/issue/ticket — see Core concepts.
• Proposals are accept or reject only. There’s no “revise” tool; you reshape a proposal in the review conversation and Tekk re-drafts.
• Goals are read-only over MCP — the app is where you set direction.

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).
• 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.

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.