---
title: "Installing Corridor MCP"
description: "Connect agents to Corridor MCP and expose the MCP endpoint for external access."
---

import { Tabs, TabItem } from '@astrojs/starlight/components';

Corridor MCP provides agents with access to Corridor through the Model Context Protocol (MCP). It runs over HTTP and uses OAuth to authenticate users.

An administrator exposes the MCP endpoint for the deployment once. After that, each user connects their own agent to it.

## Connecting an agent

Once the MCP endpoint has been exposed for your deployment, it is available at:

```text
https://<mcp-deployment>
```

The exact hostname depends on how your deployment routes the endpoint. See [Hosting the MCP endpoint](#hosting-the-mcp-endpoint) for what an administrator needs to configure, and check with whoever manages your deployment if you are unsure of the URL.

The endpoint is added as a remote MCP server in the agent. The server name is local to the agent and can be anything you choose. The examples below use `corridor`.

<div class="client-tabs">
<Tabs>
  <TabItem label="Claude Code">

```bash
claude mcp add --transport http corridor https://<mcp-deployment>
claude mcp login corridor
```

  </TabItem>
  <TabItem label="Codex">

Add the server to the Codex configuration:

```ini
[mcp_servers.corridor]
url = "https://<mcp-deployment>"
```

Then authenticate:

```bash
codex mcp login corridor
```

  </TabItem>
  <TabItem label="VS Code">

Add the server from the Command Palette with **MCP: Add Server → HTTP**, or add it to `.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "corridor": {
      "type": "http",
      "url": "https://<mcp-deployment>"
    }
  }
}
```

To make the server available across all workspaces instead, use **MCP: Open User Configuration** and add the same entry there.

VS Code prompts for sign-in the first time the server is used. Do not add an authorization header.

  </TabItem>
  <TabItem label="Copilot CLI">

```bash
copilot mcp add --transport http corridor https://<mcp-deployment>
```

The server is added to `~/.copilot/mcp-config.json` and is available immediately without restarting the CLI. You can also add it interactively with `/mcp add`.

  </TabItem>
  <TabItem label="Zed">

Add a remote server from **Settings → AI → MCP Servers → Add Server → Add Remote Server**, or add it to the settings file:

```json
{
  "context_servers": {
    "corridor": {
      "url": "https://<mcp-deployment>"
    }
  }
}
```

Do not add an `Authorization` header. Zed uses the standard MCP OAuth flow when no authorization header is configured.

  </TabItem>
</Tabs>
</div>

Other MCP clients use the same endpoint. The exact configuration depends on the client.

## Authentication

When an agent connects for the first time, it opens the Corridor login page. The user signs in and selects the workspace they want to use.

There is no separate MCP login. External agents use Corridor's existing login and OAuth flow, and users sign in using whatever authentication methods are configured for their deployment, such as password, OTP, or [SAML](/technology/installation/components/authentication-setup/saml/).

The client stores the access token and sends it with subsequent requests. The MCP server uses the identity in the token to apply the user's Corridor permissions.

A session is associated with the workspace selected during sign-in. To connect to a different workspace, the user needs to authenticate again.

## Hosting the MCP endpoint

The Corridor App Server (`corridor-app`) starts the MCP server alongside the main application and keeps it running.

For external access, MCP is given its own domain and exposed through a [reverse proxy](/technology/installation/components/web-server/). Everything on that domain belongs to the MCP server, so a single `location` block is enough and no individual routes need to be listed.

```nginx
server {
    listen 443;
    server_name mcp.corridor.example.com;

    # The MCP server owns its endpoint and OAuth discovery routes.
    location / {
        proxy_pass http://corridor-app-service:8899;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
    }
}
```

> The proxy must support long-lived HTTP connections and disable response buffering for streamed MCP responses.
>
> The MCP port should only be reachable by the reverse proxy. Users should connect through the HTTPS endpoint instead.

## Configuration

The MCP endpoint used for OAuth is determined by the following settings, in order:

| Priority | Setting | Purpose |
| --- | --- | --- |
| 1 | `CORRIDOR_MCP_URL` | The public MCP URL. Set this when MCP has its own domain |
| 2 | `CORRIDOR_APP_URL` | Falls back to the application origin if no MCP URL is set |
| 3 | `MCP_HOST` / `MCP_PORT` | Used when running MCP directly |

The main MCP settings are:

| Setting | Purpose |
| --- | --- |
| `CORRIDOR_MCP_ENABLED` | Enables or disables MCP. Default: enabled |
| `CORRIDOR_MCP_HOST` | Host on which MCP listens |
| `CORRIDOR_MCP_PORT` | Port on which MCP listens. Default: `8899` |
| `CORRIDOR_MCP_URL` | Explicit MCP URL when the default URL needs to be overridden |
| `CORRIDOR_APP_URL` | Public application origin used for OAuth issuer discovery |

Keeping the MCP URL separate from the application URL also allows in-platform requests to use the internal endpoint rather than going through the public application URL.

## Common troubleshooting

Check in this order:

1. `corridor-app` is running and MCP is enabled.
2. The `mcp` endpoint is reachable from the client.
3. The public URL uses HTTPS.
4. The OAuth discovery paths are routed to the MCP server.
5. Proxy buffering is off.
6. The user has permission to read the objects they are asking about.