Harbor: An MCP gateway that connects AI clients to back end APIs via tools

Notifications You must be signed in to change notification settings

Fork 0

Star 5

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1 Commit

1 Commit

.github

.github

adapters

adapters

core

core

docs

docs

examples

examples

runtime

runtime

services

services

spi

spi

tests

tests

tools

tools

wiring

wiring

.dockerignore

.dockerignore

.env.example

.env.example

.gitignore

.gitignore

.gitleaks.toml

.gitleaks.toml

.nvmrc

.nvmrc

API_STABILITY.md

API_STABILITY.md

CHANGELOG.md

CHANGELOG.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

Dockerfile

Dockerfile

GOVERNANCE.md

GOVERNANCE.md

LICENSE

LICENSE

NOTICE

NOTICE

README.md

README.md

ROADMAP.md

ROADMAP.md

SECURITY.md

SECURITY.md

eslint.config.js

eslint.config.js

index.ts

index.ts

package-lock.json

package-lock.json

package.json

package.json

tsconfig.json

tsconfig.json

vitest.config.ts

vitest.config.ts

Repository files navigation

A production-grade Model Context Protocol (MCP) gateway that connects AI clients to your existing backend APIs — without modifying those APIs.

Read the full article on Medium →

The Problem

When an AI (Claude, Cursor, GPT) needs to interact with your backend APIs, it has no way to know what endpoints exist, what parameters they take, how to authenticate, or what business rules apply.

The standard fix — generating one MCP tool per endpoint — doesn't scale. A realistic API has hundreds of endpoints that overwhelm any AI context window.

Harbor takes a different approach: Code Mode. Instead of one tool per endpoint, the AI gets five general-purpose tools and writes JavaScript to interact with your API. The gateway runs that code in an isolated V8 sandbox, validates every call, and forwards it to your backend with proper auth and circuit breaking — all without changing a line of your API code.

AI client → Harbor → Your backend APIs │ ├── V8 sandbox isolation ├── Per-service auth (OAuth 2.1 / static token) ├── Circuit breaker + retry └── Audit logging

Features

Five MCP tools — discover_services, discover_skills, get_skill_details, search_code, api_execute

V8 sandbox isolation — AI-written JavaScript cannot access the network, filesystem, or framework internals

Pluggable auth — static-token, oauth-introspection, jwt-validation (local JWKS, no AS round-trip), oauth-2.1 (RFC 8414/OIDC auto-discovery)

OAuth 2.1 Protected Resource — RFC 9728 discovery metadata, WWW-Authenticate on 401, full MCP auth flow

Pluggable backends — register custom token-cache backends without forking the codebase

Per-service configuration — each service declares its own auth, circuit breaker, and spec source

Zero API changes — your backend never changes; Harbor is a pure adapter

Service skills — Markdown SOP files the AI reads before making API calls

Circuit breaker — count-based, per endpoint, per service

Structured audit logging — every api_execute call logged with code, endpoints, duration, outcome

Streamable HTTP + stdio — both MCP transports supported

Quick Start

Prerequisites: Node.js 22+, npm 10+, native build tools (Xcode CLT on macOS / build-essential on Linux)

git clone https://github.com/vdssinha/harbor cd harbor npm install

Run the demo (three local backends + MCP gateway):

bash examples/demo/start.sh

Verify (E2E smoke test, stdlib only):

python3 tests/demo_e2e.py --start-services

Connect Cursor (~/.cursor/mcp.json):

{ "mcpServers": { "harbor": { "url": "http://127.0.0.1:3333/mcp", "headers": { "Authorization": "Bearer " } } } }

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

{ "mcpServers": { "harbor": { "url": "http://127.0.0.1:3333/mcp", "headers": { "Authorization": "Bearer " } } } }

Full setup guide → docs/getting-started.md

Documentation

Guide What it covers

docs/getting-started.md Full setup, demo walkthrough, Cursor integration

docs/service-onboarding.md Adding services, full config.json reference

docs/skill-authoring.md Writing skills — frontmatter, api.request() patterns, error handling

docs/configuration.md All environment variables

docs/adapter-guide.md Custom connectors — Redis, gRPC, GraphQL

docs/oauth-2.1-guide.md OAuth 2.1 setup and auth strategies

docs/architecture.md System design, layers, extension points

docs/tool-layer.md MCP protocol, sandbox model, tool contracts

docs/request-lifecycle.md End-to-end request trace

docs/faq.md Troubleshooting and common questions

ROADMAP.md Planned features and milestones

Development

npm run dev # tsx watch — live reload npm test # vitest — 312 unit + integration tests npm run typecheck # tsc --noEmit (strict) npm run build # tsc → dist/

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, coding guidelines, PR process, and good first issues.

License

Apache License 2.0 — see LICENSE.

By contributing you agree your contributions will be licensed under Apache 2.0.

About

TypeScript MCP gateway that connects AI agents to backend APIs via the Model Context Protocol — pluggable auth, V8 sandbox execution, circuit breaker, and audit logging.

Topics

ai

tooling

skills

mcp

service-discovery

gateway

plugin-system

adapter-pattern

extensible-framework

agentic-ai

model-context-protocol

mcp-server

mcp-gateway

context-engineering

Resources

Readme

License

View license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

5 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

1 tags

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 91.4%

Python 8.0%

Other 0.6%