MCP gateway

Create a workspace MCP gateway in Tessl and connect to it from any agent with `tessl mcp proxy`.

A workspace MCP gateway lets Tessl broker connections to an external Model Context Protocol 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 <workspace>/<mcp>.

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 (<workspace>/<mcp>) 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:

tessl mcp proxy <workspace>/<mcp>

• <workspace> is the workspace slug (the same one used in registry URLs).
• <mcp> is the server name you chose when creating the gateway.

For example, with a workspace named engteam and an MCP server named linear:

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.

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 for the shape your agent expects.

A typical .mcp.json-style entry looks like:

{
  "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, and a workspace gateway is just another stdio MCP server from the plugin's perspective. Add an entry that invokes tessl mcp proxy:

{
  "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 — the registry MCP server (tessl mcp start) versus the workspace gateway (tessl mcp proxy).
• Configuration files — how .mcp.json is shaped and discovered.
• Custom agent setup — how individual agents read MCP server entries.