ToolBridge — Secure MCP Server for Authenticated Tool Execution

Streamable HTTP is the production transport; stdio is used only for local development and rapid iteration.

ToolBridge is a production-grade MCP (Model Context Protocol) server that exposes authenticated, authorized external tools to any MCP-compatible client. It enforces per-user authentication, per-user authorization, secure credential handling, tool-level permissions, audit logging, failure handling, and observability. MCP-compatible AI agents and clients connect to ToolBridge to access its tools — the agent/client itself is not part of this project.

Architecture

MCP-compatible Client or AI Agent (external — not part of this project)
  ↓
MCP (Streamable HTTP — production | stdio — local dev)
  ↓
ToolBridge MCP Server
  ↓
Authentication
  ↓
Authorization / Policy
  ↓
Tool Executor
  ↓
External APIs (GitHub REST API)

The server combines two concerns, kept deliberately separate:

Related MCP server: Broker

Phase Status

Technology Decisions

Current Implementation (Phases 1–4)

Future Phases (not yet implemented)

Phase 4 — MCP Transport & Protocol — ✅ COMPLETE

Integrated the MCP Streamable HTTP transport into the FastAPI application, enabling real MCP clients to connect over the network. The server now fully supports end-to-end tool execution over HTTP, distinct from the in-process testing implemented in Phase 2.

What was delivered

Phase 3 — GitHub Tool Integrations — ✅ COMPLETE

Implemented the GitHubClient — a typed, async HTTP client wrapping the GitHub REST API — and wired all three MCP tools to it. Tools now make real API calls and return live data. Phase 3 raises the test count from 4 to 11 passing tests while maintaining 0 Ruff issues and 0 mypy issues.

What was delivered

Pull Request Filtering in list_issues

GitHub's REST API returns pull requests as part of the issues endpoint (a PR is technically a kind of issue in their data model). Each raw item includes a "pull_request" key only if it is actually a PR. GitHubClient.list_issues filters those out so the tool returns genuine issues only, matching what the tool name promises callers.

Base64 Decoding in get_file_contents

GitHub's Contents API returns file content as a Base64-encoded string. GitHubClient.get_file_contents decodes it to a UTF-8 string before returning, so callers receive human-readable text without needing to know about the encoding layer. If the target path is a directory (response is a JSON array rather than an object), the client raises GitHubClientError with a clear "directory" message.

Error Handling

All three client methods map GitHub HTTP status codes to typed exceptions before surfacing them:

Phase 2 — MCP Server Core — ✅ COMPLETE

Implemented the core ToolBridge MCP server using the MCP 2.x MCPServer API (mcp.server.mcpserver.MCPServer). The server exposes three discoverable MCP tools with explicit Pydantic input/output schemas, backed by in-process tests that cover both tool invocation and MCP tool discovery. Phase 2 maintains the quality bar established in Phase 1: 4 passing tests, Ruff passing with 0 issues, and mypy passing with 0 issues.

What was delivered

MCP SDK Version Drift & Migration

During Phase 2 a real MCP SDK version-drift issue was encountered and deliberately resolved.

Initial implementation used the MCP 1.x API:

from mcp.server.fastmcp import FastMCP

The problem: when the virtual environment was recreated and dependencies were resolved, uv resolved MCP 2.1.1 (the latest available version satisfying the broad mcp>=1.9.0 constraint in pyproject.toml). The mcp.server.fastmcp module does not exist in MCP 2.x, causing:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Deliberate resolution: rather than silently adapting code until the error disappeared, the project treated this as a real API compatibility issue and deliberately migrated from the MCP 1.x FastMCP API to the MCP 2.x MCPServer API:

MCP 1.x
FastMCP  (mcp.server.fastmcp)
    ↓
API / version drift discovered (mcp.server.fastmcp absent in MCP 2.x)
    ↓
MCP 2.x
MCPServer  (mcp.server.mcpserver)

The final import in the implementation is:

from mcp.server.mcpserver import MCPServer

The uv.lock was updated as part of this resolution and now pins the resolved version to MCP 2.1.1. The pyproject.toml dependency constraint (mcp>=1.9.0) remains broad enough to have admitted MCP 2.x; constraining it to mcp>=2,<3 would pin the project to MCP 2.x while preventing an uncontrolled future major-version API change from silently breaking the server. That constraint update is tracked as a follow-on hygiene item.

MCP Tools

Three read-oriented tools are registered on the MCP server as of Phase 3:

search_repositories(query)              → SearchRepositoriesResult
list_issues(repo, state="open")         → ListIssuesResponse
get_file_contents(repo, path)           → FileContentsResponse

These tools are discoverable (verified by test_tools_are_discoverable_with_schemas), return schema-driven structured output (verified by the three invocation tests), and make real GitHub REST API calls via GitHubClient (Phase 3).

Planned Database Schema

users (id, github_username, created_at)
user_tokens (id, user_id, provider, access_token, refresh_token NULL, expires_at NULL, scopes[])
tool_permissions (id, user_id, tool_name, allowed)
audit_log (id, user_id, tool_name, request_payload, response_status, latency_ms, created_at)

Note: refresh_token and expires_at are intentionally nullable. The exact GitHub token lifecycle will be verified during Phase 5 before the schema is finalised.

Getting Started (Phases 1–4)

Prerequisites

• Python 3.12+

• uv

• Docker & Docker Compose

• A GitHub personal access token (for tool execution)

Setup

# Clone and enter the project
git clone <repo-url>
cd toolbridge

# Copy environment configuration
cp .env.example .env
# Edit .env — set GITHUB_TOKEN to your GitHub personal access token

# Install dependencies
uv sync

# Start PostgreSQL
docker compose up -d

# Run the application
uv run uvicorn toolbridge.main:app --reload

# Verify health
curl http://localhost:8000/health
# {"status":"ok","db":"ok"}

Running Tests

# Unit tests (no external services required)
uv run pytest tests/unit/

# GitHub client tests (uses respx HTTP mocks — no real API calls)
uv run pytest tests/github/

# MCP server tests (uses respx HTTP mocks — no real API calls)
uv run pytest tests/mcp/

# Integration tests (requires PostgreSQL from docker compose up -d)
uv run pytest tests/integration/ -m integration

# All tests
uv run pytest

Code Quality

# Linting
uv run ruff check .

# Formatting check
uv run ruff format --check .

# Type checking
uv run mypy .

Database Migrations

# Run pending migrations
uv run alembic upgrade head

# Create a new migration
uv run alembic revision --autogenerate -m "description"

Project Structure

toolbridge/
│
├── src/
│   └── toolbridge/
│       ├── config/       # Typed settings (pydantic-settings)
│       ├── logging/      # Structured logging (structlog)
│       ├── db/           # Async SQLAlchemy engine + health check
│       ├── server/       # FastAPI application + MCP HTTP transport (Phase 4)
│       ├── github/       # GitHub REST API client + typed responses (Phase 3)
│       └── mcp/          # MCP server instance + tool definitions (Phase 2–3)
│
├── tests/
│   ├── unit/             # Tests with no external service dependencies
│   ├── integration/      # Tests requiring PostgreSQL
│   ├── mcp/              # MCP server and HTTP transport tests (Phase 2–4)
│   └── github/           # GitHub client unit tests with respx mocks (Phase 3)
│
├── migrations/           # Alembic migration scripts
├── docs/                 # Architecture documentation
├── scripts/              # Development utility scripts
├── .github/workflows/    # GitHub Actions CI
│
├── pyproject.toml        # Project metadata, dependencies, tool config
├── Dockerfile            # Multi-stage production image
├── docker-compose.yml    # Local development environment (PostgreSQL)
├── .env.example          # Environment variable reference (no secrets)
└── README.md

Observability

Logs are emitted in JSON format in production and human-readable format in development. Every log record includes: timestamp, level, logger, message.

Future phases will add: request_id, user_id, tool_name, latency_ms, status.

Security Notes

• Secrets are never committed. The .env file is in .gitignore.

• See .env.example for all required environment variables.

• OAuth credentials, JWT secrets, and API keys are out of scope until Phase 5/7.

Engineering Decisions & Implementation Notes

MCP SDK Version Drift (Phase 2)

During Phase 2, MCP SDK version drift exposed an API incompatibility between the original MCP 1.x FastMCP implementation and the MCP 2.x package resolved by uv (mcp==2.1.1). The issue was resolved deliberately by migrating the server from FastMCP to MCPServer and updating the code to the MCP 2.x API at mcp.server.mcpserver.

This keeps the implementation aligned with the resolved MCP major version. Constraining the pyproject.toml dependency to mcp>=2,<3 is tracked as a follow-on step to prevent an uncontrolled future major-version upgrade from introducing another breaking API change.

GitHub Client Design (Phase 3)

GitHubClient is a thin, typed wrapper around httpx.AsyncClient. Each method maps to a single GitHub REST API endpoint and converts HTTP error codes into a typed exception hierarchy before they propagate to the MCP tool layer. This keeps error handling logic out of the MCP tool handlers themselves and makes the client testable in isolation with respx HTTP mocks — no real network calls are required by any unit test.