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

# MCP best practices

> Security, OAuth, and troubleshooting for Tess Custom MCP and the hosted Tess MCP Server.

Use this page for security, OAuth, and troubleshooting across both Tess MCP surfaces: the hosted [Tess MCP Server](/en/api-mcp) and [Custom MCP](/en/mcp-custom) (Tess as client).

## Hosted Tess MCP Server

* Point clients at `https://mcp.tess.im` with **Streamable HTTP**. There is no local `npx` process.
* Send **both** headers on every request: `Authorization: Bearer …` and `x-workspace-id`. There is no query-parameter fallback.
* Use a **dedicated API token** per integration so you can revoke it without rotating everything else.
* In Cursor, interpolate an environment variable for the token instead of saving it in plaintext (`url` and `headers` support env interpolation).
* In Claude Code, remote JSON entries need `type` set to `http` (or `streamable-http`). A `url` without `type` is skipped as a broken stdio server.
* The tool list is an **allow-list of the public API**, not every internal endpoint. If a tool is missing, it is not on the public surface yet.

## Custom MCP (Tess as client)

* Only **remote Streamable HTTP** endpoints. Local stdio / `npx` servers cannot run inside Tess.
* Prefer **OAuth** when the provider supports it. Each person who uses a shared OAuth MCP must click **Connect** with their own account.
* Keep personal-identity servers **personal**. Sharing a WhatsApp or personal inbox MCP lets teammates opt in and call those tools. See [Sharing and permissions](/en/mcp-sharing-permissions).
* Do not enable a server in chat until **Connect** succeeds. An OAuth server with no token cannot run.
* Turn off tools you do not need. Chips are per user and do not change a teammate's selection.
* If a server has no usable credential for you, Tess **hides** it from discovery (fail-closed) instead of calling it unauthenticated.

## Troubleshooting

| Symptom                                  | What to check                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Hosted server connects but no tools      | Transport is Streamable HTTP, URL is exactly `https://mcp.tess.im`, Claude Code `type` is `http` |
| 401 / unauthorized                       | Both headers present; token active in the dashboard                                              |
| Custom MCP missing in chat               | You opted in; the server is connected; it is selected under Connectors                           |
| OAuth popup never finishes               | Allow pop-ups; complete the provider login; click Connect again                                  |
| Shared MCP visible to you but tools fail | Connect **your** OAuth account; governors cannot share someone else's OAuth token                |

## Related

* [MCP Server](/en/api-mcp)
* [Custom MCP](/en/mcp-custom)
* [Sharing and permissions](/en/mcp-sharing-permissions)
* [Model Context Protocol](https://modelcontextprotocol.io)