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

# Troubleshooting

> Fixes for the things that go wrong when connecting an MCP client to Connie — OAuth failures, attribution placeholders, 401s, 403s, and stuck caches.

If you're stuck, work through the section that matches your symptom. Most issues resolve with a config tweak or clearing the local OAuth cache.

If nothing on this page matches, contact [support@connie.ai](mailto:support@connie.ai) with your IDE, the Connie URL you're using, and the timestamp of the failed request.

***

## Consent screen shows the MCP CLI placeholder

If the OAuth consent screen says **"MCP CLI Proxy wants to connect to your Connie workspace"** (or `"MCP CLI Client"` on older `mcp-remote` builds) instead of your IDE's name, your install snippet is missing the `--static-oauth-client-metadata` flag. `mcp-remote` registers with a generic placeholder by default, and the consent screen renders whatever `client_name` was sent at DCR time.

**Fix it once, properly:**

<Steps>
  <Step title="Update your install snippet">
    Re-copy the snippet for your IDE from the [client setup page](/mcp/clients) — every snippet there includes `--static-oauth-client-metadata '{"client_name":"<IDE>"}'`. The flag is the bit that makes the consent screen attribute correctly.
  </Step>

  <Step title="Clear mcp-remote's OAuth cache">
    `mcp-remote` reuses its previous DCR registration on every startup, so just updating the snippet isn't enough — you also need to force a fresh DCR with the new `client_name`:

    ```powershell theme={null}
    # Windows
    Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"
    ```

    ```bash theme={null}
    # macOS / Linux
    rm -rf ~/.mcp-auth
    ```
  </Step>

  <Step title="Fully restart your IDE">
    Quit and reopen. A window reload is not enough — the MCP subprocess only respawns on a full app restart.
  </Step>

  <Step title="Re-authorize">
    The next tool call opens the consent screen again, this time with the correct IDE name.
  </Step>
</Steps>

### Already authorized and don't want to re-consent?

The Connected Apps row gets upgraded automatically when you make a tool call — Connie reads `clientInfo.name` from the MCP `initialize` handshake and updates the row from the placeholder to your IDE's name in the background. **But the consent screen has already passed by that point, so this fallback fixes Connected Apps, not the consent UX.** If the consent-screen attribution mattered, you need to follow the steps above to force a re-authorization.

If the Connected Apps row stays as the placeholder **after** a successful tool call, your client identified itself with a `clientInfo.name` Connie doesn't recognize — check that you're on a current `mcp-remote` build, then file an issue with the verbose `--debug` output from a fresh handshake.

***

## OAuth flow opens but I get 401 after authorizing

The token was minted but isn't being accepted on subsequent requests. Common causes:

* **Stale token in your config.** If you pasted a token literal into the config file, remove it — the OAuth flow stores tokens in `~/.mcp-auth/`, not in your client config. Static tokens belong to the [workspace API key](/mcp/api-key) path, not OAuth.
* **Account changed mid-flow.** If you signed in to a different Connie account than the one you usually use, the token is bound to that other identity. Revoke and re-authorize from the right account.
* **Token expired mid-call.** Access tokens are 1h; refresh tokens are 30d. After 30d of inactivity the grant is invalid — re-authorize.

To force a clean re-auth, [clear the local OAuth cache](#mcp-remote-doesnt-re-trigger-oauth-even-after-restart) and restart your client.

***

## Tool call returns 403 / "forbidden"

Looks like:

```json theme={null}
{
  "error": "forbidden",
  "error_description": "You are not a member of the requested workspace."
}
```

The OAuth grant inherits whatever workspaces your account is a member of — it can't expand that set. Three things to check:

* **You're hitting a workspace you no longer belong to.** Membership may have been removed. Ask the workspace admin to re-add you, or remove the `?workspaceId=` pin from your config to fall back to your default workspace.
* **You typoed the workspace ID.** Compare against `list-my-workspaces` output — ask your IDE: *"What Connie workspaces do I have access to?"*
* **The tool call is targeting a workspace from a per-tool argument.** Some tools accept `workspaceId` as a parameter; the AI may have inferred the wrong one. Be explicit in your prompt.

See [Multi-workspace](/mcp/workspaces) for the full picture of how workspace selection resolves.

***

## Revoking from Connected Apps doesn't immediately stop the client

Revoke marks every token tied to that client as revoked. The next MCP request from that client gets a `401 Unauthorized` with a `WWW-Authenticate` header, which prompts the client to bootstrap a fresh OAuth flow.

What this means in practice:

* **Already-in-flight requests** complete normally — Connie doesn't kill open connections mid-stream.
* **Cached tool listings** may still appear in your IDE's UI until the next tool call.
* **The very next tool call** triggers the consent screen again.

If you need a hard stop (offboarding, compromise), revoke is the right action — within seconds the client can't make a new authenticated request.

***

## Revoking opens a consent screen loop (every few seconds)

Symptom: you clicked Revoke in Connected Apps while your IDE was still running, and now your browser keeps opening new consent tabs every few seconds — even when you click Cancel on one, another opens almost immediately.

**This is expected behavior, not a bug.** Here's why it happens:

1. Your IDE's MCP loop fires a request every few seconds (heartbeat / tool refresh / etc.).
2. Each request now returns `401 Unauthorized` because the token was revoked.
3. `mcp-remote` sees the 401 + `WWW-Authenticate` header and treats it as "I need to re-authenticate" — it has no memory across MCP request ticks that you just denied the previous prompt.
4. New browser tab opens. You click Cancel. The deny propagates to `mcp-remote`, but the next IDE tick fires another request and the cycle restarts.

We surface a warning banner on the consent screen when this is happening (Connie detects that the same client was revoked within the last 5 minutes), but the only way to actually stop the loop is to break it at the IDE side.

**To stop the loop:**

<Steps>
  <Step title="Close all the consent tabs">
    Don't worry about answering Allow or Cancel — they'll keep reopening until step 2.
  </Step>

  <Step title="Remove the MCP server entry from your IDE config">
    Edit the relevant file (`~/.cursor/mcp.json` for Cursor, `~/.claude/settings.json` for Claude Code, etc.) and delete the `connie` block, or comment out the whole `mcpServers` section.
  </Step>

  <Step title="Fully restart your IDE">
    The MCP subprocess (`mcp-remote`) only dies on a full app restart. A window reload doesn't kill it.
  </Step>

  <Step title="Re-add and reconnect (optional)">
    If you wanted to re-authorize rather than disconnect entirely, restore the `connie` entry in your config and restart the IDE again. A fresh OAuth flow starts on the next tool call.
  </Step>
</Steps>

**To avoid the loop in the first place:** when planning to revoke, remove the MCP server entry from your IDE config *first*, restart the IDE, *then* click Revoke. No consent tabs at all.

***

## `EADDRINUSE` on the callback port

Shouldn't happen if you're using `mcp-remote` with `0` as the positional port — the OS hands back a free ephemeral port every time.

You'll see this if:

* An older snippet pinned a specific port (e.g. `6190` / `6191`). Switch the positional port arg to `0` and the collision class disappears.
* A firewall pinhole or corporate policy forces a specific port. Identify what's holding the port and kill it:

```powershell theme={null}
# Windows
$blockerPid = (Get-NetTCPConnection -LocalPort 6190 -State Listen -ErrorAction SilentlyContinue).OwningProcess
if ($blockerPid) { Stop-Process -Id $blockerPid -Force }
```

```bash theme={null}
# macOS / Linux
lsof -nP -iTCP:6190 -sTCP:LISTEN
kill -9 <pid>
```

***

## `mcp-remote` doesn't re-trigger OAuth even after restart

`mcp-remote` caches OAuth state under `~/.mcp-auth/` so it doesn't open a browser tab on every IDE start. If you've revoked, changed accounts, or want a guaranteed-fresh handshake, clear the cache:

```bash theme={null}
# macOS / Linux
rm -rf ~/.mcp-auth
```

```powershell theme={null}
# Windows
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcp-auth"
```

Then fully restart your IDE (not a window reload — the MCP subprocess only respawns on a full restart for most clients).

***

## My favorite Connie tool isn't showing up

Connie's MCP server exposes a curated **v1 surface** of \~25 GTM-headline tools (CRM, Inbox, Flows, the top integrations) in `tools/list`. The long tail — niche workspace-builder tools, admin operations, specialized integrations — is **discoverable but not pre-listed**.

Your AI can find them at runtime:

```
Search Connie tools for "flow trigger advanced"
```

This calls `search-tools` and returns matches. Then:

```
Get details for the tool ID it returned
```

That calls `get-tool-details`, which gives the AI the schema it needs to invoke the tool. From the user's perspective: just ask for what you want, the AI does the discovery.

If a tool you expect is genuinely missing — not just not pre-listed — contact [support@connie.ai](mailto:support@connie.ai).

***

## What's next

<CardGroup cols={2}>
  <Card title="Overview" icon="book-open" href="/mcp/overview">
    Auth modes, attribution, and which path fits your use case.
  </Card>

  <Card title="Client setup" icon="grid-2" href="/mcp/clients">
    Copy-paste configs for all four supported IDEs.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.