Metadata-Version: 2.4
Name: opus-mcp-proxy
Version: 0.1.0
Summary: MCP proxy that connects Claude Desktop/Code to the OPUS Operator platform
Author: OPUS Engineering
License: MIT
License-File: LICENSE
Keywords: claude,mcp,operator,opus,proxy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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:

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

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

```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):

```json
{
  "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):

```json
{
  "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:

```bash
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

```bash
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](LICENSE).
