---
title: "MCP server setup"
description: "Step-by-step setup to connect Claude, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, Codex CLI, and more to the Middleware MCP Server."
section: "Ops AI"
breadcrumb: "Ops AI > MCP Server > Setup"
canonical: "https://docs.middleware.io/features/mcp/setup"
---
# MCP server setup

Connect **Middleware MCP Server** to your AI assistant or IDE to access observability data directly from your development environment.

Once connected, you can query logs, metrics, traces, application errors, and other Middleware data using natural language. You can also perform supported operations such as creating and managing dashboards.

Middleware provides a hosted MCP Server, so you don't need to install or maintain a separate server.

This guide covers connecting Middleware MCP Server to Claude, Cursor, VS Code, Windsurf, Gemini CLI, Codex, and other MCP-compatible clients.

## Prerequisites

Before connecting, make sure you have:

- **Middleware Account** — An account with access to the project you want to query.
- **MCP-Compatible Client** — An AI assistant or IDE that supports remote MCP servers over HTTP with OAuth.
- **Web Browser** — Required to sign in and authorize the connection.

## MCP Server Endpoint

All supported clients connect to the same Middleware MCP endpoint:

`https://mcp.middleware.io/mcp`

Use this URL when configuring Middleware as an MCP server.

If your client asks for a transport type, select **HTTP**, which may also appear as **Streamable HTTP** or **Remote**.

## How Authentication Works

Middleware MCP Server uses OAuth authentication, so you don't need to manually generate or paste an access token.

#### 1 Add the endpoint to your client

Configure `https://mcp.middleware.io/mcp` as a remote MCP server (see the steps for your client below).

#### 2 Sign in to Middleware

Your client opens a browser window. Log in to your Middleware account.

#### 3 Select your project and approve

On the authorization screen, select the project in your account that you want to connect, then approve the requested access.

#### 4 Start using the tools

Once you approve, the client connects and the Middleware tools appear in your assistant. Your sign-in is reused on future sessions, so you only do this once.

Once authorized, your AI assistant can access the available Middleware MCP tools.

The authenticated session is reused for future connections, so you generally don't need to sign in again.

![Middleware MCP authorization screen showing project selection and access](/images/opsai/mcp-server/oauth-authorize.png)

## Connect Middleware MCP Server

Select your preferred AI assistant or IDE and follow the corresponding setup instructions.

#### Claude Code

Register the server with the CLI:

```bash
claude mcp add --transport http middleware https://mcp.middleware.io/mcp
```

Then run `/mcp` inside Claude Code, select **middleware**, and choose **Authenticate**. Your browser opens; sign in, select your project, and approve.

To configure it by hand, add this to `~/.claude.json` (or a project `.mcp.json`):

```json
{
  "mcpServers": {
    "middleware": {
      "type": "http",
      "url": "https://mcp.middleware.io/mcp"
    }
  }
}
```

#### Claude

Middleware is listed in the Claude connectors directory, so you can connect it directly from Claude on the web, desktop, or mobile without entering a URL:

1. Go to **Settings → Connectors**.
2. Find **Middleware** in the connectors directory and click **Connect**.
3. Sign in to your Middleware account, select your project, and approve.

Open a new chat, click the tools icon, and make sure the **Middleware** connector is enabled.

> **Note:** Prefer a walkthrough? [Watch the demo](/features/mcp/details#watch-the-demo) of connecting Middleware from Claude connectors.

**Add it as a custom connector instead**

If you do not see Middleware in the directory (for example, in some organization-managed workspaces), add it as a custom connector:

1. Go to **Settings → Connectors** and click **Add custom connector**.
2. Set the name to **Middleware** and the URL to `https://mcp.middleware.io/mcp`, then click **Add**.
3. Click **Connect**, sign in, select your project, and approve.

> **Note:** Custom connectors are available on Claude paid plans.

#### Cursor

Add the server to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "middleware": {
      "url": "https://mcp.middleware.io/mcp"
    }
  }
}
```

Open **Cursor Settings → MCP & Integrations**, click **Needs login** next to **middleware**, then sign in, select your project, and approve.

#### VS Code

Add a `.vscode/mcp.json` file in your workspace, or run **MCP: Add Server → HTTP** from the Command Palette:

```json
{
  "servers": {
    "middleware": {
      "type": "http",
      "url": "https://mcp.middleware.io/mcp"
    }
  }
}
```

Click **Start** above the server entry, sign in, select your project, and approve. Then open Copilot Chat in **Agent** mode and confirm the Middleware tools under the **Tools** button.

> **Note:** VS Code uses the `servers` key, not `mcpServers`.

#### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`, or use **Settings → Cascade → MCP Servers → Add custom server**:

```json
{
  "mcpServers": {
    "middleware": {
      "serverUrl": "https://mcp.middleware.io/mcp"
    }
  }
}
```

In **Settings → Cascade → MCP Servers**, click **Refresh**, then sign in, select your project, and approve.

#### Antigravity

Open the **MCP Store** (`...` menu → **Manage MCP Servers → Add custom server**), or edit `mcp_config.json`:

```json
{
  "mcpServers": {
    "middleware": {
      "serverUrl": "https://mcp.middleware.io/mcp"
    }
  }
}
```

Refresh the server list, then sign in, select your project, and approve. If authorization fails, run **Authentication: Remove Dynamic Authentication Providers** and reconnect.

#### Gemini CLI

Register the server with the CLI:

```bash
gemini mcp add --transport http middleware https://mcp.middleware.io/mcp
```

Or add it to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "middleware": {
      "httpUrl": "https://mcp.middleware.io/mcp"
    }
  }
}
```

Start Gemini CLI, run `/mcp auth middleware`, then sign in, select your project, and approve.

#### Codex CLI

Register the server with the CLI:

```bash
codex mcp add middleware --url https://mcp.middleware.io/mcp
```

Or add it to `~/.codex/config.toml`:

```toml
[mcp_servers.middleware]
url = "https://mcp.middleware.io/mcp"
```

Run `codex mcp login middleware`, then sign in, select your project, and approve.

#### Other clients

Any client that supports remote MCP servers over HTTP with OAuth can connect. Use this configuration (field names vary by client):

```json
{
  "mcpServers": {
    "middleware": {
      "type": "http",
      "url": "https://mcp.middleware.io/mcp"
    }
  }
}
```

On first connect, the client opens your browser to sign in. Select your project and approve. Common field-name variations: VS Code uses `servers`; Windsurf and Antigravity use `serverUrl`; Gemini CLI uses `httpUrl`.

## Verify Your MCP Connection

Once connected, open your AI assistant and ask a question about your Middleware data.

For example:

- `List all my dashboards in Middleware.`
- `What resource types are available in my Middleware account?`
- `Show me the errors from the last hour.`

Your assistant will use the available Middleware MCP tools to retrieve the requested information.

If it returns the expected data, your MCP connection is working.

For the complete list of supported operations, see [Middleware MCP Tools](/features/mcp/tools).

## Restrict MCP Tool Access

Middleware MCP Server allows you to restrict the tools available to a specific connection.

For example, if you want your AI assistant to access observability data without modifying dashboards or widgets, you can exclude write operations.

Add the `exclude_tools` query parameter to the MCP endpoint:

`https://mcp.middleware.io/mcp?exclude_tools=create_dashboard,update_dashboard,delete_dashboard,clone_dashboard,set_dashboard_favorite,create_widget,update_widget,delete_widget,update_widget_layouts`

This configuration removes the listed write tools from the MCP connection.

Excluded tools are hidden from the client and cannot be called.

You can customize the comma-separated list to restrict specific operations.

For the available tool names, [Middleware MCP Tools](/features/mcp/tools).

## Troubleshooting

### Browser Authentication Does Not Open

If your client does not open the sign-in page:

1. Verify that your client supports remote MCP servers with OAuth.
2. Retry the authentication action.
3. If your terminal displays an authentication URL, open it manually in your browser.

### Incorrect Project Data

If your assistant returns data from the wrong project or no data:

1. Disconnect or sign out of the Middleware MCP connection.
2. Reconnect the server.
3. Select the correct Middleware project during authorization.

The MCP Server uses the project selected during authentication.

### Middleware Tools Are Not Available

If you cannot see Middleware tools in your AI assistant:

1. Confirm that the MCP server is enabled.
2. Verify the endpoint:
   `https://mcp.middleware.io/mcp`
3. Ensure that your client is running in a mode that supports tools, such as Agent mode in Cursor or VS Code.
4. Reconnect if required.

### Write Operations Fail

If your assistant cannot create or update dashboards or widgets:

1. Check whether the required tool is excluded using `exclude_tools`.
2. Verify that your Middleware account has permission to modify the selected project.
3. Update the configuration and reconnect if needed.

### Connection Timeout

If the MCP connection drops or times out:

1. Verify that your network allows outbound HTTPS connections to `mcp.middleware.io` and `app.middleware.io`.
2. Check whether a proxy or network configuration is removing the `Authorization` header.
3. Retry the connection.

If the issue continues, contact Middleware Support with your MCP client name, version, and error message.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us page or join our Slack channel.