Open Agent Connector

An open-source, self-hosted integration gateway for AI agents. Connect accounts to app APIs, keep credentials in your own runtime, and let agents discover and run actions through the Model Context Protocol (MCP) or a REST API.

This project is for developers who want to inspect, run, and extend their own agent integration layer. It is an open-source option to evaluate alongside Composio, Nango, Merge.dev, and Arcade.dev. Those platforms offer broader catalogs and managed capabilities; Open Agent Connector currently prioritizes a compact self-hosted implementation that you can modify.

Project description

Open Agent Connector gives an agent a consistent way to discover connected services, find an action, read its input schema, and execute it. A FastAPI backend manages provider definitions, connections, outbound requests, and run records. A Next.js console provides screens for browsing providers and actions, managing connections and runtime tokens, and reviewing activity. SQLite stores application data locally by default.

The current built-in providers are GitHub, Slack, Hacker News, and Custom HTTP. The GitHub catalog contains 147 action definitions. The other providers have a smaller set of focused actions. The catalog is code-defined and intentionally extensible; it is not a claim of broad coverage across third-party apps.

Features

• MCP gateway: supports JSON-RPC methods for initialization, ping, tool discovery, and tool execution over POST /mcp.
• Action discovery: agents can list providers, search actions, inspect action guides and schemas, and execute actions.
• Direct MCP actions: provider actions are also exposed as individual MCP tools, alongside five discovery and execution tools.
• REST API: list providers and actions, execute an action, or use a provider proxy where supported.
• Connections: save named provider connections; credential values are encrypted before they are stored.
• Local web console: browse the catalog, configure connections, and view token and run-log screens.
• Request safeguards: outbound HTTP requests check destination addresses to block private and internal targets by default. Cloud metadata and loopback targets remain blocked.
• Idempotent execution: action requests can use an Idempotency-Key; matching completed requests can return a saved response instead of repeating the upstream call.
• Run records: action executions record status, timing, and bounded input/output summaries for inspection.
• Extensible providers: provider and action definitions live in Python, with the GitHub action catalog in JSON.

How it compares

These products overlap in connecting apps to software and AI agents, but they have different scopes. Composio centers on a large app toolkit and agent execution platform. Nango focuses on building and operating product integrations, including auth and sync. Merge.dev provides unified APIs and common models across product integration categories. Arcade.dev focuses on agent-ready tools, authentication, and runtime controls. Open Agent Connector is a smaller self-hosted project for teams who want to own and extend the integration service.

Choose based on the catalog breadth, managed operations, authentication, security controls, and support your application needs. Open Agent Connector has a smaller catalog and fewer production operations features than those established services.

Architecture

Agent or application
        │
        ├── MCP JSON-RPC: POST /mcp
        └── REST: /v1/*
                │
        FastAPI action runtime
        ├── provider and action registry
        ├── connection and credential handling
        ├── guarded outbound HTTP client
        └── run logs and idempotency records
                │
        SQLite database + external provider APIs

Next.js web console ───────────────┘

Stack

Area	Technology
Web console	Next.js App Router, React, TypeScript, Tailwind CSS
API and runtime	FastAPI, Python, Pydantic
Persistence	SQLite, SQLAlchemy async, aiosqlite
Credential encryption	AES-256-GCM via cryptography
Agent interface	MCP JSON-RPC over HTTP

Built-in providers

Provider	Authentication	Examples
GitHub	Personal access token or OAuth access token	Repository, issue, pull request, workflow, and user actions from the JSON catalog
Slack	Bot or OAuth access token	Post a message and list channels
Hacker News	None	Get top stories, retrieve an item, and search stories
Custom HTTP	None or API key	Send an SSRF-guarded HTTP request to an external HTTP or HTTPS endpoint

Provider availability and action inputs are defined by the running catalog. Query GET /v1/providers and GET /v1/actions for the current schemas.

Quick start

Requirements

• Python 3.11 or newer
• Node.js and npm

1. Run the API

cd server
python -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
uvicorn main:app --host 127.0.0.1 --port 8000 --reload

On Windows PowerShell, activate the environment with:

venv\Scripts\Activate.ps1

The API creates its SQLite database and a local encryption key on first startup if they do not exist. For a durable deployment, configure and back up a stable key before saving credentials; losing the key makes previously encrypted credentials unreadable.

2. Run the web console

Open another terminal from the repository root:

cd client
npm install
npm run dev

Open http://localhost:3000. The console uses http://localhost:8000 for the API by default. Set NEXT_PUBLIC_API_URL before starting or building the frontend to use a different API URL.

Local service URLs

• Web console: `http:/