> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# MCP gateway

The **MCP gateway** lets Tessl broker connections to an external [Model Context Protocol](https://modelcontextprotocol.io) server, such as a third-party integration your agents call. Tessl stores the upstream credentials (client secret, tokens) and relays each request with them. Nobody copies those credentials into an agent configuration or re-runs the OAuth flow.

This page covers external servers. For the Tessl registry MCP server that `tessl mcp start` runs, see [MCP tools](/reference/mcp-tools.md).

Your organization holds its MCP servers. An organization admin registers and authorizes each one. A run can reach an organization MCP server only when its environment names that server, and only projects bound to that environment run with it. Registration alone doesn't give any run access to a server. Naming a server in an organization environment isn't yet available in the web app or the CLI. To name a server in an organization environment, contact [support@tessl.io](mailto:support@tessl.io). See [MCP servers](/administrators/least-privilege-environments.md#mcp-servers) in the least-privilege guide.

## Register an MCP server in your organization

You need the organization admin role. Workspace owners and managers who aren't organization admins can't add a server: the workspace's **MCP servers** page tells them to ask an organization admin.

1. Open your organization's settings in the Tessl web app and go to **MCP servers**.
2. Click **Add MCP server**.
3. Fill in the form:
   - **Server name**: unique in the organization. An environment refers to the server by this name. `new` is reserved. Example: `linear`.
   - **Upstream URL**: the URL of the MCP server. Example: `https://mcp.example.com`.
   - **Transport**: `HTTP` or `SSE`, matching how the upstream server exposes itself.
   - **Optional OAuth overrides**: leave these blank to use the upstream provider's discovery defaults. Fill them in to pin a specific client, scope, resource, or authorization server:
     - **Client ID** and **Client secret**: a 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**: the RFC 8707 resource indicator for the upstream API.
     - **Authorization server URL**: an explicit authorization server, for when discovery doesn't point at the right one.
4. Click **Add MCP server**.

The server appears in the list with the status **Not connected**.

## Authorize the server

1. On the organization's **MCP servers** page, click **Connect** on the server's row.
2. Sign in with the upstream provider. When it returns, the status changes to **Connected**.
3. Optionally, click **Test connection** to check that Tessl can reach the server with the stored credentials.

If sign-in stops working upstream, the status changes to **Reconnect needed**. Click **Reconnect** to sign in again.

The **Used by environments** column lists the environments that name each server. **Delete** removes the server from the organization.

## Servers moved from a workspace

Workspace owners and managers used to register servers in their own workspace. Tessl moved those servers into the organization. The organization's **MCP servers** page shows each one as **Moved from** its former workspace. It marks a server **Renamed** when the server took a new name to stay unique in the organization.

A moved server keeps working in its former workspace:

- Runs in that workspace can still name it directly, with no environment, by its old name or its new one.
- An existing workspace environment that named it still reaches it.
- Members of that workspace can still call it with `tessl mcp proxy <workspace>/<mcp>`.

Bindings don't limit this access.

A workspace that still holds servers of its own lists them under **Settings → Integrations → MCP servers**. A workspace owner or manager can authorize or delete them there, but nobody can add a new server.

## Who can do what

- **Organization admin**: registers, authorizes, tests, and deletes organization MCP servers.
- **Workspace owner or manager who isn't an organization admin**: can't register a server. Can authorize or delete a server the workspace still holds.
- **Workspace member**: can call a server the workspace still holds, or one moved from it, with `tessl mcp proxy`.
- **A run**: reaches an organization server only when its environment names it, and a moved server also through its former workspace.

## Connect to the gateway with `tessl mcp proxy`

`tessl mcp proxy` connects you, or any agent you run, to a server through a workspace: one the workspace still holds, or one moved from it into the organization. Any member of the workspace can connect once the server is authorized:

```sh
tessl mcp proxy <workspace>/<mcp>
```

- `<workspace>` is the workspace slug (the same one used in registry URLs).
- `<mcp>` is the server's name. For a moved server, its old workspace name and its organization name both work.

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 servers 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 `tessl mcp proxy` 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 proxy is wired into the project's agents automatically.

## Related

- [Least privilege for environments](/administrators/least-privilege-environments.md#mcp-servers): who can reach an MCP server, and how to limit it.
- [MCP tools](/reference/mcp-tools.md): the registry MCP server (`tessl mcp start`) versus the MCP 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.