MCP Connector

A general-purpose MCP connectivity layer that bridges MCP clients to authenticated remote MCP servers. The connector acts simultaneously as an MCP server toward the downstream client and an MCP client toward upstream remote MCP servers, managing authentication, credentials, routing, and connection lifecycle in between.

The initial use case is connecting OpenHands Cloud to Notion's hosted MCP server (https://mcp.notion.com/mcp), which uses an interactive OAuth flow that is not convenient for a headless cloud agent.

    OpenHands Cloud
          │
          │ MCP
          ▼
    ┌───────────────────┐
    │   MCP Connector   │
    │                   │
    │  authentication   │
    │  credential store  │
    │  session / state  │
    │  routing          │
    └────────┬──────────┘
             │
             │ MCP + authentication
             ▼
        Remote MCP
        Server (e.g. Notion)

The connector is intentionally general-purpose. Notion is a use case, not the definition of the connector. The architecture must remain general enough to support other authenticated remote MCP servers later.

Status

Phase 0 (architecture baseline) is complete. Phase 1 (External Assumption Validation) is complete: G1, G2, G3 passed/sufficient. Phase 2 (Minimal Technical Prototype) is complete: G4 = PASS (2026-08-10) — a minimal MCP Connector forwards MCP capabilities and tool calls against a mock upstream over Streamable HTTP (stateless), with no auth, no Notion, no credential store.

The project is now at the Phase 3 entry point (Authentication and Credential Boundary). Phase 3 has not been started. The development sequence is a strict gated contract: no phase begins until the previous phase's exit gate is satisfied and documented.

Quickstart (Phase 2 prototype)

npm install
npm run build
npm run mock-upstream   # terminal 1: mock upstream on 127.0.0.1:8788/mcp
npm run connector       # terminal 2: connector    on 127.0.0.1:8789/mcp
npm test                # integration tests (3/3)
npm run smoke           # direct + relay smoke runs

See docs/ROADMAP.md for the gated phase sequence and docs/MILESTONES.md for the acceptance criteria behind each gate. Phase 2 evidence: docs/evidence/G4.md.

Documentation

Document	Purpose
docs/PROBLEM.md	The OpenHands Cloud ↔ authenticated remote MCP integration problem
docs/ARCHITECTURE.md	Proposed components, boundaries, and alternatives
docs/AUTHENTICATION.md	OAuth and credential handling, keeping upstream creds out of the sandbox
docs/MCP-FLOW.md	Downstream and upstream MCP communication
docs/ROADMAP.md	Staged development plan
docs/MILESTONES.md	Measurable milestones and acceptance criteria
docs/RISKS.md	Technical, security, architectural, and operational risks
docs/DECISIONS.md	Architectural decisions and their rationale

Goals

• Connect MCP clients to remote MCP servers.
• Support authenticated remote MCP servers (OAuth and API-key/bearer).
• Keep upstream credentials outside the MCP client sandbox.
• Forward MCP requests and responses transparently, without implementing upstream application business logic.
• Allow multiple upstream MCP servers.
• Provide a stable, simple-to-consume MCP endpoint to clients with limited connectivity or authentication capabilities.

Non-Goals

The connector is not intended to:

• replace MCP servers;
• implement Notion-specific (or any domain-specific) business logic;
• become a general-purpose project-management system;
• interpret stakeholder requirements;
• modify source repositories on its own;
• become the source of truth for project data.

The connector provides connectivity. The MCP client/agent remains responsible for deciding what tools mean and how to use them.

Design Principle: Separation of Responsibilities

Layer	Responsibility
GitHub	Implementation source of truth
OpenHands	Development agent — reasoning and execution
Notion	Development documentation and stakeholder communication
MCP Connector	Connectivity, authentication, routing, secure MCP bridging

The connector must not become a project-management or AI-reasoning layer unless a demonstrated architectural requirement forces it.

Architecture Overview

The connector sits between a downstream MCP client (initially OpenHands Cloud) and one or more upstream remote MCP servers (initially Notion). It terminates the downstream MCP session, performs upstream authentication, and forwards MCP JSON-RPC traffic transparently.

                         MCP Connector
                              │
               ┌──────────────┼──────────────┐
               │              │              │
               ▼              ▼              ▼
            Notion         GitHub        Other MCP
              MCP            MCP          Servers
               │              │              │
            OAuth        OAuth / API       Auth

The full component breakdown, boundaries, and the alternatives considered are in docs/ARCHITECTURE.md.

License

See LICENSE.