> For the complete documentation index, see [llms.txt](https://docs.tessl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tessl.io/reference/mcp-gateway.md). # MCP gateway A **workspace MCP gateway** lets Tessl broker connections to an external [Model Context Protocol](https://modelcontextprotocol.io) server for a workspace. You register the upstream server once in the workspace's settings, authorize it (via OAuth where required), and then any workspace member can connect to it through a single stable address: `tessl mcp proxy /`. A gateway is useful when: * You want a shared, authorized MCP server that every workspace member can use without each person re-running an OAuth flow. * You want to keep upstream credentials (client secret, tokens) inside Tessl rather than copy them into individual agent configurations. * You want one identifier (`/`) to reference the same MCP server from a coding agent, a plugin, or a CI environment. The gateway sits between the agent's MCP client and the upstream MCP server: the agent talks to `tessl mcp proxy` over stdio, the CLI relays JSON-RPC messages to the gateway over HTTP with Tessl auth headers, and the gateway relays them on to the upstream MCP server using the credentials you stored when you registered it. ## Create a gateway in a workspace Workspace owners and managers can register MCP servers. Members without `manage_mcp_servers` permission see the page in read-only mode. 1. Open the workspace in the Tessl web app and go to **Settings → Integrations → MCP servers**. 2. Click **Add MCP server**. 3. Fill in the form: * **Server name** — used as the slug in the gateway path. Use only alphanumerics, hyphens, and underscores (max 63 characters). Example: `linear`. * **Upstream URL** — the URL of the MCP server you are wrapping. Example: `https://mcp.example.com`. * **Transport** — `HTTP` or `SSE`, matching how the upstream server exposes itself. * **Optional OAuth overrides** — leave blank to use the upstream server's discovery defaults. Fill them in if you need to pin a specific client, scope, resource, or authorization server: * **Client ID** and **Client secret** — pre-registered OAuth client for the upstream server. The client secret is encrypted at rest. * **Scope** — space-separated OAuth scopes (for example `openid profile email`). * **Resource URL** — RFC 8707 resource indicator for the upstream API. * **Authorization server URL** — explicit authorization server, used when discovery does not point at the right one. 4. Click **Add MCP server**. The server appears in the MCP servers list with an **Unauthorized** badge. Click **Authorize** to start the OAuth flow against the upstream provider; once the upstream returns successfully, the badge flips to **Authorized** and the server is ready to use. If credentials change or expire upstream, the server is flagged as **Needs reauth**. Click **Re-authorize** to refresh; existing proxy sessions are unaffected until they reconnect. ## Connect to the gateway with `tessl mcp proxy` Once a gateway is authorized, any workspace member can connect to it through the CLI: ```sh tessl mcp proxy / ``` * `` is the workspace slug (the same one used in registry URLs). * `` is the server name you chose when creating the gateway. For example, with a workspace named `engteam` and an MCP server named `linear`: ```sh tessl mcp proxy engteam/linear ``` The command runs in the foreground and speaks the MCP protocol over its own stdin/stdout. It is intended to be launched by an MCP client (your coding agent, or any other tool that supports stdio-transport MCP servers) — running it directly in a terminal is only useful for smoke-testing connectivity. ### Authentication `tessl mcp proxy` authenticates to the gateway as the calling user: * **Interactive use** — sign in once with `tessl login`; the proxy reuses the same credentials. * **CI or other non-interactive contexts** — set the `TESSL_TOKEN` environment variable to a Tessl API key for the workspace. See [`tessl api-key create`](/reference/cli-commands.md#tessl-api-key-create). ### Use the proxy from a coding agent `tessl mcp proxy` is a standard stdio MCP server, so any agent that supports stdio-transport MCP servers can launch it. Add it to your agent's MCP configuration in the same way you would any other stdio server — see [Custom agent setup](/reference/custom-agent-setup.md) for the shape your agent expects. A typical `.mcp.json`-style entry looks like: ```json { "mcpServers": { "engteam-linear": { "command": "tessl", "args": ["mcp", "proxy", "engteam/linear"] } } } ``` You can include several gateways at once — give each one a distinct key so the agent can address them individually. ### Use the proxy from a plugin Plugins can declare MCP servers in their bundled [`.mcp.json`](/reference/configuration.md#bundled-mcp-json), and a workspace gateway is just another stdio MCP server from the plugin's perspective. Add an entry that invokes `tessl mcp proxy`: ```json { "mcpServers": { "engteam-linear": { "command": "tessl", "args": ["mcp", "proxy", "engteam/linear"] } } } ``` When a project installs the plugin, the gateway is wired into the project's agents automatically. ## Related * [MCP tools](/reference/mcp-tools.md) — the registry MCP server (`tessl mcp start`) versus the workspace gateway (`tessl mcp proxy`). * [Configuration files](/reference/configuration.md) — how `.mcp.json` is shaped and discovered. * [Custom agent setup](/reference/custom-agent-setup.md) — how individual agents read MCP server entries. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tessl.io/reference/mcp-gateway.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.