Setup - Middleware MCP Server

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.

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.

Connect Middleware MCP Server#

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

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

1{
2  "mcpServers": {
3    "middleware": {
4      "type": "http",
5      "url": "https://mcp.middleware.io/mcp"
6    }
7  }
8}

1{
2  "mcpServers": {
3    "middleware": {
4      "url": "https://mcp.middleware.io/mcp"
5    }
6  }
7}

1{
2  "servers": {
3    "middleware": {
4      "type": "http",
5      "url": "https://mcp.middleware.io/mcp"
6    }
7  }
8}

1{
2  "mcpServers": {
3    "middleware": {
4      "serverUrl": "https://mcp.middleware.io/mcp"
5    }
6  }
7}

1{
2  "mcpServers": {
3    "middleware": {
4      "serverUrl": "https://mcp.middleware.io/mcp"
5    }
6  }
7}

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

1{
2  "mcpServers": {
3    "middleware": {
4      "httpUrl": "https://mcp.middleware.io/mcp"
5    }
6  }
7}

1codex mcp add middleware --url https://mcp.middleware.io/mcp

1[mcp_servers.middleware]
2url = "https://mcp.middleware.io/mcp"

1{
2  "mcpServers": {
3    "middleware": {
4      "type": "http",
5      "url": "https://mcp.middleware.io/mcp"
6    }
7  }
8}

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.

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.

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.