Troubleshooting - Middleware MCP Server

This page covers the most common setup and runtime issues when running the Middleware MCP Server locally or connecting it to an MCP client (for example, Claude Desktop). Wherever possible, the checks below are based on what the server expects (env vars, transport mode) and what you should see on startup.

1. Build fails or the binary is not created

What to check:

• Ensure you're using Go 1.23 or later (the project uses Go 1.23.0 with toolchain 1.24.10).

What to do:

Use the standard dependency + build commands:

go mod download
go build -o mcp-middleware .

These are the same commands used in the quick start flow.

If you are using Make targets in your workflow, build using:

make install
make build

2. Server starts, but it's not authenticated or not pointing to the right project

Most common cause:

Missing or incorrect environment variables. The server relies on:

• MIDDLEWARE_API_KEY
• MIDDLEWARE_BASE_URL

What to check:

Confirm your .env (or runtime env) includes:

MIDDLEWARE_API_KEY=your_api_key_here
MIDDLEWARE_BASE_URL=https://your-project.middleware.io

What "good" looks like:

When the server starts successfully, it prints startup lines like:

• Middleware MCP Server v1.0.0
• Connected to: https://your-project.middleware.io
• Starting MCP server in stdio mode.

This is a quick sanity check that your base URL is being read correctly.

3. Claude Desktop does not show Middleware tools

This usually comes down to configuration path, command path, or not restarting the client.

What to check:

• You updated the right Claude config file for your OS:
  • machine: ~/.config/Claude/claude_desktop_config.json
• Your command points to the built binary:
  • machine example uses /full/path/to/mcp-middleware/mcp-middleware
• You restarted Claude Desktop after updating the config.

Why this matters:

Claude Desktop launches the MCP server from the command path. If the path is wrong or the binary isn't present, the MCP server won't start and the tools will not appear.

4. HTTP / SSE mode issues (can't reach the server, wrong host/port)

The server supports three transport modes:

• stdio (default)
• http (Streamable HTTP transport)
• sse (Server-Sent Events)

If you run http or sse mode, the server starts on:

• http://localhost:8080

What to check:

• Your mode is set correctly (APP_MODE=http or APP_MODE=sse).
• If 8080 doesn't work in your environment, change:
  • APP_HOST (default localhost)
  • APP_PORT (default 8080)

Known-good commands:

APP_MODE=http APP_HOST=localhost APP_PORT=8080 ./mcp-middleware

APP_MODE=sse APP_HOST=localhost APP_PORT=8080 ./mcp-middleware

5. Some tools are missing or actions are "not available"

If you intentionally (or accidentally) excluded tools, they won't be registered.

What to check:

Look for EXCLUDED_TOOLS in your environment configuration. It is a comma-separated list of tool names to exclude.

This is explicitly described as useful for read-only instances or restricting destructive operations.

Example:

EXCLUDED_TOOLS=delete_dashboard,delete_widget,create_alert

6. Getting help

If you're stuck and need support, contact:

• Middleware Support: [email protected]