> For the complete documentation index, see [llms.txt](https://docs.baas.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.baas.sh/ai-tools/mcp/troubleshooting.md).

# Troubleshooting

What to do when the BaaS MCP server doesn't connect or doesn't behave as expected.

## The server is not listed

`claude mcp list` or `codex mcp list` doesn't show `baas`.

* Claude Code registers a server for the current directory by default: run the command there, or use `--scope user`. Codex's `mcp add` writes to `~/.codex/config.toml` and applies across projects.
* The server comes from a committed file and is waiting for approval. Claude Code shows servers from `.mcp.json` as **Pending approval** until you accept them in `/mcp`. Codex reads `.codex/config.toml` in trusted projects only.

## The sign-in page doesn't open

Run the sign-in command again, `claude mcp login baas` or `codex mcp login baas`, and open the URL it prints if the browser doesn't. If sign-in keeps failing, sign out first with `claude mcp logout baas` or `codex mcp logout baas`, then sign in again. Make sure no token or header is configured on the server: the BaaS MCP signs you in itself.

## Sign-in works, but the server refuses the connection

Your account has no role on this project. Check that the URL is the one the Console shows for the project you expect, then ask a project owner for access.

## Only the inspection tools appear

Your role on the project is READ. Ask a project owner for WRITE, then sign out of the server and sign in again so the client picks up the new role. See [Permissions](/ai-tools/mcp/capabilities.md#permissions).

## The server doesn't answer

Copy the URL again from the Console and compare it with the one in your client, including the `/mcp` at the end. See [Your project's MCP URL](/ai-tools/mcp.md#your-projects-mcp-url). If they match, wait a minute and try again.

## The client reports an unsupported transport or protocol

The BaaS MCP speaks Streamable HTTP only. Make sure the server is registered with the `http` transport, not `sse`, and update your client to a recent version.

## The documentation tools fail

The documentation search is temporarily unreachable. Every other tool keeps working. Try again in a moment. In the meantime, the agent can read the documentation directly from `https://docs.baas.sh/llms.txt`, the index of every page.

## Start over

Remove the server and add it again:

{% tabs %}
{% tab title="Codex" %}

```bash
codex mcp remove baas
codex mcp add baas --url "https://my-project-api.baas.sh/mcp"
codex mcp login baas
```

{% endtab %}

{% tab title="Claude Code" %}

```bash
claude mcp remove baas
claude mcp add --transport http baas https://my-project-api.baas.sh/mcp
claude mcp login baas
```

If a project's `.mcp.json` server was declined by mistake, `claude mcp reset-project-choices` brings the approval prompt back.
{% endtab %}
{% endtabs %}