mcpassistant-gateway 0.1.2

Local outbound bridge agent for MCP capability forwarding

mcpassistant-gateway

Async local bridge that connects outbound to the remote MCP bridge over WSS and forwards invoke requests to local MCP servers using the MCP Python client library.

Run

pip install -e .
mcpassistant-gateway

mcpassistant-gateway now opens an interactive menu by default. Use /run inside the menu to start the gateway in the same terminal and view realtime logs. Press Ctrl+C while running to stop and return to the menu.

You can also use the built-in CLI helpers instead of editing config.json manually:

mcpassistant-gateway run
mcpassistant-gateway menu
mcpassistant-gateway settings
mcpassistant-gateway config show
mcpassistant-gateway config set --request-timeout-seconds 120
mcpassistant-gateway run --request-timeout-seconds 120

Inside mcpassistant-gateway menu, use slash commands:

/help
/login
/logout
/show
/set request_timeout_seconds 120
/settings
/run

/login behavior:

• OAuth-first: starts remote OAuth session, opens browser, receives localhost callback, exchanges code, and saves JWT on success.
• Legacy fallback: if OAuth endpoints are unavailable, falls back to POST /manage/jwt/issue.

For OAuth localhost callback, ensure your auth provider allows:

• http://127.0.0.1:43110/callback

mcpassistant-gateway initializes MCP client sessions for configured mcpServers (stdio) and opens the outbound bridge connection to the remote server.

Startup token behavior:

• If AGENT_JWT is already configured (env or config.json), startup continues without prompting.
• If AGENT_JWT is missing, the CLI shows a styled prompt and asks you to paste the token.
• If WebSocket auth fails with HTTP 403, the CLI asks for a fresh AGENT_JWT and retries immediately.
• AGENT_ID is auto-derived from JWT claims (or token fingerprint fallback), so no manual AGENT_ID prompt.
• Prompted values are saved into resolved config.json, so next runs do not ask again.

Set START_MCP_SERVERS=false if you only want the bridge process.

Configuration can be provided through .env and/or config.json.

If config.json does not exist, it is created automatically on first run with:

• remote_server_base_url defaulting to https://hub.linkos.in/agent
• a default mcpServers.filesystem entry scoped to your current working directory

Minimal dynamic .env:

REMOTE_SERVER_BASE_URL=https://your-remote-domain
AGENT_JWT=your_agent_jwt

With this mode:

• REMOTE_WEBSOCKET_URL is derived as wss://.../connect
• AGENT_ID and CAPABILITIES are derived from JWT claims (sub, capabilities) if not explicitly set
• Local MCP calls are handled via MCP client sessions for mcpServers

mcpServers + mcpassistant-gateway-bridge

You can run MCP servers from config (supergateway-style) and derive local HTTP endpoints:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "supergateway", "--stdio", "npx", "-y", "@modelcontextprotocol/server-filesystem", "--port", "3004"],
      "port": 3004
    }
  }
}

Run one server:

mcpassistant-gateway-bridge --config ./config.json --name filesystem

Run all servers in config:

mcpassistant-gateway-bridge --config ./config.json