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

# Connect your AI client

> Add the Waniwani MCP server to claude.ai, Claude Code, Cursor, or ChatGPT and sign in with your Waniwani account — no API keys.

Waniwani runs the MCP server in two regions. Add the URL for the region where your organization lives:

| Region | MCP URL                          |
| ------ | -------------------------------- |
| US     | `https://mcp.waniwani.ai/mcp`    |
| EU     | `https://eu.mcp.waniwani.ai/mcp` |

It's a remote MCP server (Streamable HTTP) that authenticates with OAuth 2.1. There is no API key to paste: you add the URL, your client opens a browser window, you sign in to Waniwani and approve the requested permissions. From then on the connection acts as *you* — same organizations, same role.

<Note>
  Each region is an independent stack with its own data. Sign in on the endpoint that matches your **data residency** — the region you chose when you [created your organization](/platform/regions). The US endpoint won't show organizations that live in the EU, and vice versa. The examples below use the US URL; if your data is in the EU, swap in `https://eu.mcp.waniwani.ai/mcp`.
</Note>

## Claude (claude.ai and desktop)

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter `https://mcp.waniwani.ai/mcp` and confirm.
4. A Waniwani sign-in window opens — sign in and approve the permissions.

On Team and Enterprise plans, an admin may need to enable custom connectors for your workspace first.

## Claude Code

```bash theme={null}
claude mcp add --transport http waniwani https://mcp.waniwani.ai/mcp
```

Then run `/mcp` inside Claude Code and select **waniwani** to complete the browser sign-in.

## Cursor

Add the server to `~/.cursor/mcp.json` (or **Settings → MCP → Add new MCP server**):

```json ~/.cursor/mcp.json theme={null}
{
  "mcpServers": {
    "waniwani": {
      "url": "https://mcp.waniwani.ai/mcp"
    }
  }
}
```

Cursor prompts you to authenticate in the browser the first time it connects.

## ChatGPT

Custom MCP connectors require developer mode:

1. Open **Settings → Apps & Connectors → Advanced settings** and enable **Developer mode**.
2. Back in **Connectors**, click **Create** and enter `https://mcp.waniwani.ai/mcp`.
3. Complete the sign-in when prompted.

<Note>
  Client UIs change quickly. If a menu has moved, follow your client's own guide for adding a **remote MCP server** and use the URL above — the server implements the standard discovery flow, so any MCP-capable client that supports OAuth can connect.
</Note>

## What happens when you sign in

<Steps>
  <Step title="Your client discovers Waniwani">
    The client reads the server's metadata and learns which Waniwani stack handles sign-in for that region (`app.waniwani.ai` for US, `eu.app.waniwani.ai` for EU). It registers itself automatically — no manual client IDs.
  </Step>

  <Step title="You sign in to Waniwani">
    The browser opens your usual Waniwani login. If you're already signed in, you go straight to consent.
  </Step>

  <Step title="You approve the permissions">
    The consent screen itemizes exactly what the connection may do (read environments and analytics, create environments and keys, and so on). You only see permissions your account is entitled to.
  </Step>

  <Step title="Connected">
    The client receives a token bound to this server and your approved permissions. Every call it makes runs under your identity.
  </Step>
</Steps>

## First thing to try

> Who am I signed in to Waniwani as, and what can you do for me here?

Your client will call the server's `whoami` and `search` tools and report your account, your organizations, and the available operations. From there, ask for what you want in plain language — see [the overview](/mcp-server/overview) for example prompts.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The consent screen shows fewer permissions than I expected">
    That's by design. The permission list is narrowed to what your account is entitled to — for example, internal Waniwani staff permissions never appear for customer accounts. Approve what's shown; it's everything available to you.
  </Accordion>

  <Accordion title="Calls suddenly fail with an authentication error">
    Your token expired or was invalidated. Most clients refresh automatically; if yours doesn't, disconnect and reconnect the server (re-running the sign-in) to mint a fresh token.
  </Accordion>

  <Accordion title="I can't switch to another organization (NOT_ORG_MEMBER)">
    `set_active_org` only switches to organizations you belong to — the API rejects anything else with a `NOT_ORG_MEMBER` error. Ask *"who am I?"* — the `whoami` tool lists the organizations you can act on and their ids.
  </Accordion>

  <Accordion title="I switched organizations in the dashboard, but this connection still uses the old one">
    Expected. Each connection carries its own active organization, independent of the dashboard — switching in one place doesn't switch the other. Ask the model to switch here too (it calls `set_active_org`), or check where you stand with *"who am I?"*.
  </Accordion>

  <Accordion title="The model says an operation doesn't exist">
    The available surface is curated and grows over time. Ask the model to run `search` again — it returns the live catalog with exact signatures. If what you need isn't there yet, tell us.
  </Accordion>
</AccordionGroup>