---
title: "MCP Client Setup"
description: "Configure an MCP client for Tanda and check compatibility"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.testandaccept.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Client Setup

Tanda's AI assistant and tools are available over the [Model Context Protocol](https://modelcontextprotocol.io). Connection requires a client with compatible protocol support, Streamable HTTP, and OAuth. Setup instructions below cover Claude Code, Claude Desktop, claude.ai, Cursor, ChatGPT, Codex, and Pi. Your assistant can then read your projects and statements of work, add task items, acceptance criteria and tests, draft whole SOWs for your approval, find coverage gaps, and work with requests for change (RFCs) and root cause analyses (RCAs).

**Endpoint:** `https://agents.testandaccept.com/mcp`
**Transport:** Streamable HTTP
**Authentication:** OAuth. You sign in with your Tanda account; there's no API key to copy.

> **Caution**
>
> Pi users: browser sign-in can succeed while the MCP connection fails with
> `Unsupported protocol version: 2025-11-25`. See [Pi compatibility](/integrations/pi/#protocol-version-error)
> before connecting. Signing in again does not resolve this version mismatch.

> **Note**
>
> The old endpoint `mcp.testandaccept.com`, which used a `TANDA-API-KEY` header, has been retired.
> If you set it up before, remove that entry and add the new endpoint below.

1. **Add the Server to Your Client**

   ### Claude Code

   ```bash
   claude mcp add --transport http tanda https://agents.testandaccept.com/mcp
   ```

   Then run `/mcp` inside Claude Code, select **tanda**, and choose **Authenticate**.

   If you belong to several Tanda organizations, add the one this machine works in so you never have to name it (see [Choosing a default organization](#choosing-a-default-organization)):

   ```bash
   claude mcp add --transport http tanda https://agents.testandaccept.com/mcp --header "Tanda-Organization: acme"
   ```

   ### claude.ai / Claude Desktop

   1. Open **Settings → Connectors**.
   2. Click **Add custom connector**.
   3. Set **Name** to `Tanda` and **URL** to `https://agents.testandaccept.com/mcp`.
   4. Set **Authentication** to **Sign in now** and **OAuth client** to **Register automatically**. Leave **Request headers** empty.
   5. Click **Add**, then **Connect** and sign in.

   Connectors added on claude.ai are also available in Claude Desktop. For a walkthrough of every setting, see [Connecting Claude, step by step](/integrations/claude/#connecting-claude-step-by-step).

   ### Cursor

   Add this to `~/.cursor/mcp.json` (or **Settings → MCP → Add Server**):

   ```json
   {
     "mcpServers": {
       "tanda": {
         "url": "https://agents.testandaccept.com/mcp",
         "headers": { "Tanda-Organization": "acme" }
       }
     }
   }
   ```

   Cursor opens the sign-in page the first time it connects. The `headers` line is optional: it names the organization your requests default to (see [Choosing a default organization](#choosing-a-default-organization)).

   ### ChatGPT

   1. Go to **Plugins** ([chatgpt.com/plugins](https://chatgpt.com/plugins)), select **+**, then **Add custom MCP server**. This needs developer mode.
   2. Name it `Tanda`, set the server URL to `https://agents.testandaccept.com/mcp`, and choose **OAuth** with no client ID or secret.
   3. Create it and sign in.

   Full read and write access needs a Business, Enterprise or Edu plan. See [ChatGPT Integration](/integrations/chatgpt/) for every step.

   ### Codex

   ```bash
   codex mcp add tanda --url https://agents.testandaccept.com/mcp
   codex mcp login tanda
   ```

   The Codex CLI, IDE extension and ChatGPT desktop app share this setup. To default to one organization, add `http_headers = { "Tanda-Organization" = "acme" }` to the server's block in `config.toml`. See [Codex Integration](/integrations/codex/).

   ### Pi

   Check the [Pi compatibility notice and setup guide](/integrations/pi/) first.
   For Pi's built-in MCP support, configure Tanda and sign in:

   ```bash
   pi mcp add tanda --url https://agents.testandaccept.com/mcp
   pi mcp login tanda
   pi mcp list
   ```

   The connection must succeed before tools are available. If it reports protocol error
   `-32022`, follow the [protocol-version guidance](/integrations/pi/#protocol-version-error).

   ### Project .mcp.json

   To give everyone on a repository the same setup, commit this file. There are no secrets in it, because each person signs in with their own account:

   ```json
   {
     "mcpServers": {
       "tanda": {
         "type": "http",
         "url": "https://agents.testandaccept.com/mcp",
         "headers": { "Tanda-Organization": "acme" }
       }
     }
   }
   ```

   `headers` is optional. With it, everyone working in this repository defaults to that organization (its slug, name or ID), and nobody has to name it in their requests. Each person still only reaches organizations they belong to.
2. **Sign In and Approve Access**

   Your client opens a browser window:

   1. **Sign in** to Tanda with Google, GitHub, Microsoft, or email and password.
   2. **Organizations.** One connection works in every organization you belong to; the consent screen lists them. If you belong to several, name the organization in your request ("in Acme, …"), or choose one once (see [Choosing a default organization](#choosing-a-default-organization)).
   3. **Approve access:**
      - **Read** (`tanda:read`): view projects, SOWs and their versions, task items, criteria, tests, RFCs and root cause analyses.
      - **Write** (`tanda:write`): create and update them.

   You can only reach projects and SOWs that you have access to in Tanda. The connection never gives you more access than your account already has.
3. **Try It**

   Ask your assistant:

   - "List my Tanda projects."
   - "Which acceptance criteria in SOW *Website Rebuild* have no tests?"
   - "Draft a SOW for a marketing site rebuild on a headless CMS, then show it to me before saving."

   See [Claude Integration](/integrations/claude/) for the full list of tools and example workflows.

## Choosing a Default Organization

If you belong to several Tanda organizations, tools that list or create things need to know which one you mean. Rather than naming it in every request, choose it once:

- **Desktop and web apps** (Claude, ChatGPT): tell the assistant, for example "Work in Acme from now on." It calls `set_default_organization`, and Tanda remembers the choice for that connection until you change it ("Clear my default Tanda organization"). Each connection has its own default, so your Claude and ChatGPT connections can differ.
- **IDEs and command-line tools** (Claude Code, Cursor, Codex): send a `Tanda-Organization` header with the organization's slug, name or ID. Set it per repository in that repository's MCP configuration, as in the examples above, and each project defaults to its own organization.

When a request names an organization, that always wins. Then the header, if your client sends one; then the stored default; then your only organization, if you have just one. Tools that take a record ID (a SOW, task item or criterion) work in that record's organization regardless. Tanda checks your membership on every request: a default for an organization you've left is ignored, and a header naming one you don't belong to is refused.

Ask "Which Tanda organization am I working in?" at any time: `list_organizations` reports the default in effect and where it comes from.

## What You Can Do

| Area | Read | Write |
|---|---|---|
| Organizations | `list_organizations`, `set_default_organization` (remembers your choice for the connection) | — |
| Projects | `list_projects`, `get_project` | — |
| Statements of work | `list_sows`, `get_sow` | `create_sow` |
| Task items | `list_task_items`, `get_task_item` | `create_task_item`, `update_task_item` |
| Acceptance criteria | `list_acceptance_criteria` | `create_acceptance_criterion`, `update_acceptance_criterion` |
| Tests | `list_tests` | `create_test` |
| Code test settings | `get_execution_settings` | `save_execution_settings` |
| Code test runs | `get_code_test_runs` | `manage_code_test_run` (configure bindings, start runs, cancel result collection) |
| Analysis | `analyze_coverage`, `analyze_requirements_completeness`, `analyze_coverage_gaps` | — |
| Drafting help | `draft_sow_from_description`, `propose_tests_from_criteria` | — |
| Assistant | `ask_tanda` | — |
| SOW generation | — | `start_sow_generation`, `resume_sow_generation` (waits for your approval) |

> **Caution**
>
> These are not available over MCP yet: deleting records, clients and contacts, user stories,
> manual test run entry, and project members and invitations. Use the Tanda web app for those.

For connected repository tests, follow the [IDE testing workflow](/integrations/ide-testing-workflow/) or [automated acceptance testing guide](/features/automated-testing/). A runner connection is required before code tests can execute.

## Troubleshooting

| Symptom | Fix |
|---|---|
| Pi says "Signed in" but connection fails with `400`, `-32022`, or `Unsupported protocol version` | Sign-in succeeded, but the client and server protocols are incompatible. See [Pi protocol-version error](/integrations/pi/#protocol-version-error); repeating sign-in will not fix it. |
| `401` and your client asks you to sign in | You're not signed in, or the session expired. Authenticate again (in Claude Code: `/mcp` → **tanda** → **Authenticate**). |
| "you belong to several organizations; pass organization to choose one" | Name the organization in your request, or choose one once: see [Choosing a default organization](#choosing-a-default-organization). |
| "Tanda-Organization header: organization … not found" | Your MCP configuration names an organization you don't belong to, or misspells its slug. Fix the header, or ask the assistant to list your organizations. |
| "this connection is limited to …" | The connection predates multi-organization support. Disconnect and connect again once to reach all of your organizations. |
| `403 insufficient_scope` on create or update | You didn't approve write access. Reconnect and approve **Write**. |
| `403 … does not exist or you do not have access` | The ID is wrong, the record is in an organization you don't belong to, or you don't have access to that project. Check the ID with a list tool, or ask a project owner for access. |
| claude.ai sign-in fails right after **Connect** | Set the connector's **OAuth client** to **Register automatically**, not *Use Claude's published identity*. |
| Claude Code keeps using an old URL | An older entry overrides `.mcp.json`. Check with `claude mcp list`, then remove the stale one, e.g. `claude mcp remove tanda -s local`. |
| Connection to `mcp.testandaccept.com` fails | That endpoint is retired. Remove the entry and add `https://agents.testandaccept.com/mcp`. |
| Tools don't appear | Restart the client. In Claude Code, check with `claude mcp list`. |

## Removing the Connection

```bash
claude mcp remove tanda
```

On claude.ai, remove the connector under **Settings → Connectors**. For JSON-configured clients, delete the `tanda` entry and restart.

### Native client callback errors

Pi, Codex, and other native clients return from browser sign-in to a registered local callback such as `http://127.0.0.1:45123/callback`. Tanda permits the port to change between logins, while requiring the hostname, path, and query to match the registration. `localhost`, `127.0.0.1`, and `[::1]` are separate callback hosts.

If sign-in returns `invalid_redirect`, restart the client's MCP login to generate a fresh authorization URL. If you changed the callback hostname or path, clear that client's Tanda OAuth registration and reconnect so it can register the new callback. Do not replace the callback with the Tanda website URL; the local MCP client needs to receive the authorization response. When reporting a persistent failure, include only the `client_id` and `redirect_uri` from the generated URL, not tokens or authorization codes.

Source: https://docs.testandaccept.com/integrations/mcp-setup/index.mdx