opus-mcp-proxy 0.1.0

MCP proxy that connects Claude Desktop/Code to the OPUS Operator platform

opus-mcp-proxy

MCP proxy that connects Claude Desktop and Claude Code to the OPUS Operator platform. Tenants authenticate with an API key and get access to operator tools — no IAM credentials, no AWS setup required.

Connection Methods

There are three ways to connect, from most seamless to most portable:

Method 1: Claude Code — Remote HTTP (recommended)

Zero install. Claude Code natively supports remote MCP servers over Streamable HTTP:

claude mcp add --transport http opus-operator https://main.d1nrdsq2gd55ub.amplifyapp.com/api/mcp

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "opus-operator": {
      "type": "http",
      "url": "https://main.d1nrdsq2gd55ub.amplifyapp.com/api/mcp",
      "headers": {
        "Authorization": "Bearer opus_k_..."
      }
    }
  }
}

Method 2: Claude Desktop — Custom Connector (recommended)

Zero install, zero config files. Claude Desktop connects via the Connectors UI:

1. Open Claude Desktop
2. Go to Settings → Connectors → Add custom connector
3. Paste the MCP endpoint URL: https://main.d1nrdsq2gd55ub.amplifyapp.com/api/mcp
4. Add your API key as the Bearer token when prompted
5. Save and start a new chat

This works because the control plane speaks full MCP Streamable HTTP transport. Anthropic's cloud connects directly to the endpoint.

Method 3: Local stdio proxy via uvx (fallback)

For environments where remote connections are blocked (private networks, firewalls, air-gapped systems), or older Claude Desktop versions without Custom Connector support:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "opus-operator": {
      "command": "uvx",
      "args": ["opus-mcp-proxy@latest"],
      "env": {
        "OPUS_API_KEY": "opus_k_...",
        "OPUS_CONTROL_PLANE_URL": "https://main.d1nrdsq2gd55ub.amplifyapp.com"
      }
    }
  }
}

Claude Code (if HTTP transport unavailable):

{
  "mcpServers": {
    "opus-operator": {
      "command": "uvx",
      "args": ["opus-mcp-proxy@latest"],
      "env": {
        "OPUS_API_KEY": "opus_k_...",
        "OPUS_CONTROL_PLANE_URL": "https://main.d1nrdsq2gd55ub.amplifyapp.com"
      }
    }
  }
}

Environment Variables (Method 3 only)

Variable	Required	Default	Description
OPUS_API_KEY	Yes	—	Your tenant API key from the Connect page
OPUS_CONTROL_PLANE_URL	No	http://localhost:3100	URL of the OPUS control plane

Getting an API Key

1. Log into the OPUS control plane dashboard
2. Navigate to the Connect page
3. Click Generate API Key
4. Copy the key (starts with opus_k_) into your config

Verifying It Works

After configuring your client:

1. Restart Claude Desktop (or reload MCP servers in Claude Code)
2. Start a new conversation
3. Ask: "What tools do you have?"
4. Claude should list the OPUS Operator tools available to your tenant

You can also verify the local proxy installation:

opus-mcp-proxy --version

Which Method Should I Use?

Scenario	Method
Claude Code (any version)	Method 1 — Remote HTTP
Claude Desktop (current)	Method 2 — Custom Connector
Behind corporate firewall	Method 3 — uvx local proxy
No Node.js or Python installed	Method 2 — Custom Connector
Older Claude Desktop (pre-Connectors)	Method 3 — uvx local proxy
Air-gapped / offline network	Method 3 — uvx local proxy

Troubleshooting

"ERROR: OPUS_API_KEY not set" (Method 3)

The proxy starts without a key (graceful degradation) but requests will fail. Make sure OPUS_API_KEY is set in your config's env block.

"HTTP 401: Unauthorized"

Your API key is invalid or expired. Generate a new one from the Connect page.

"HTTP 403: Forbidden"

Your tenant doesn't have access to the requested tool. Contact your admin to check permissions.

Connection refused / timeout

• Verify the control plane URL is correct and reachable
• Check your network connection and any VPN/proxy settings
• For Custom Connectors: the URL must be publicly reachable (no localhost)
• For uvx: ensure Python 3.10+ is installed

Claude doesn't show any tools

• Ensure the MCP server name matches exactly
• Check Claude Desktop/Code logs for MCP connection errors
• Restart the client after config changes
• For Custom Connectors: verify TLS certificate is valid (no self-signed)

Development

cd mcp-proxy
pip install -e .
OPUS_API_KEY=test OPUS_CONTROL_PLANE_URL=http://localhost:3100 opus-mcp-proxy --version

License

MIT — see LICENSE.