universal-connector-mcp

<!-- mcp-name: io.github.TeodorMCP/universal-connector-mcp -->

<div align="center">

# Universal API Connector MCP

![Universal API Connector - Any API. One MCP server.](https://raw.githubusercontent.com/TeodorMCP/universal-connector-mcp/main/assets/banner.png)

### Any API. One MCP server.

Stop installing a new MCP server for every service: point this one at any OpenAPI/Swagger, GraphQL,<br>
gRPC or SOAP spec - or pick one from the built-in catalog of **2500+ public APIs** - and your AI agent<br>
can call it. Securely, in fewer steps, with fewer tokens.

[![CI](https://img.shields.io/github/actions/workflow/status/TeodorMCP/universal-connector-mcp/ci.yml?label=CI)](https://github.com/TeodorMCP/universal-connector-mcp/actions)
[![PyPI](https://img.shields.io/pypi/v/universal-connector-mcp)](https://pypi.org/project/universal-connector-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[![Add to Cursor](https://img.shields.io/badge/%E2%86%92%20Add%20to-Cursor-black?style=for-the-badge)](cursor://anysphere.cursor-deeplink/mcp/install?name=universal-connector&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ1bml2ZXJzYWwtY29ubmVjdG9yLW1jcCJdfQ==)

[Installation](#installation) · [Meta-tools](#meta-tools) · [API catalog](#built-in-api-catalog) · [Examples](#example-session) · [Configuration](#configuration) · [Security](#security-model)

![Live demo: the agent discovers, loads and calls an API in a single session](https://raw.githubusercontent.com/TeodorMCP/universal-connector-mcp/main/assets/demo.gif)

</div>

## Why another one?

Most "universal API" MCP servers only speak REST/OpenAPI. This project is built around three differentiators:

1. **Truly universal** - a normalized `Operation` model with pluggable spec adapters (OpenAPI, GraphQL, gRPC, SOAP). Tools and executors never care which protocol produced an operation.
2. **Security-first / local-first** - a direct response to supply-chain attacks like the *AgentBaiting / FakeGit* campaign. Outbound requests are restricted to an allowlist, secrets never touch logs, responses are size-capped, and every call is audit-logged. No arbitrary code execution, no binary downloads, no telemetry.
3. **Built for context efficiency** - field-level response filtering, chained and parallel execution, and response caching mean whole workflows fit in one tool call and responses stay small.

## How it works

![One connector, every protocol](https://raw.githubusercontent.com/TeodorMCP/universal-connector-mcp/main/assets/how-it-works.png)

The agent explores APIs like a filesystem instead of loading hundreds of tools at once (which would blow up the context window on large APIs like Stripe). It searches for operations, inspects the ones it needs, then executes them.

<details>
<summary>Architecture (click to expand)</summary>

```mermaid
flowchart TD
    Agent["AI Agent"] -->|"MCP stdio"| Server["FastMCP Server"]
    Server --> Tools["Meta-tools"]
    Tools --> Registry["Operation Registry (normalized)"]
    Adapters["Spec Adapters"] --> Registry
    Tools --> Guard["Security Guard"]
    Guard --> Executor["Protocol Executors"]
    Executor --> Auth["Auth Manager"]
    Executor --> UpstreamAPI["Upstream API"]
```

</details>

## Meta-tools

| Tool | Purpose |
| --- | --- |
| `search_catalog` | Find ready-to-load public APIs (curated list + APIs.guru directory, 2500+ specs) |
| `load_api` | Register an API from a spec URL/file (protocol auto-detected) |
| `list_apis` | List loaded APIs |
| `search_operations` | Fuzzy-search operations across loaded APIs |
| `get_operation` | Full parameter/response schema for one operation |
| `execute` | Call an operation (auth + security guard applied); `extract` returns only the fields you ask for |
| `execute_chained` | Run a sequence of operations in one call, piping results between steps; nested lists run in parallel |
| `execute_graph` | Run a dependency graph of operations; order is inferred from `${id.path}` references and independent nodes run in parallel automatically |
| `unload_api` | Remove a loaded API |
| `audit_log` | Recent outbound calls (method, host, path, status) |

## Why fewer steps (and fewer tokens)

![Fewer steps, fewer tokens](https://raw.githubusercontent.com/TeodorMCP/universal-connector-mcp/main/assets/fewer-steps.png)

Where a per-API MCP server needs one tool round-trip per call - each returning a full JSON payload into the agent's context - this server collapses whole workflows:

- **`extract`** - `execute(..., extract=["items.*.name", "total_count"])` returns just those fields instead of a multi-kilobyte response. `*` fans out over arrays.
- **Chaining** - `execute_chained` pipes step results into later params via `${save_as.path}` references: one tool call instead of N.
- **Parallel groups** - a nested list of steps runs concurrently, so "query three APIs and combine" is still one call:

```text
execute_chained(steps=[
  [
    {"operation_id": "github.repos_get", "params": {"owner": "o", "repo": "r"},
     "save_as": "gh", "extract": ["stargazers_count"]},
    {"operation_id": "open_meteo.get_v1_forecast", "params": {"latitude": 52.5, "longitude": 13.4},
     "save_as": "weather", "extract": ["current_weather.temperature"]}
  ],
  {"operation_id": "github.issues_list_for_repo",
   "params": {"owner": "o", "repo": "r"}, "extract": ["*.title"]}
])
```

- **Response cache** - successful GET/query results are cached for `UCMCP_CACHE_TTL` seconds (default 60), so repeated lookups are instant and free; pass `fresh: true` to bypass. Successful mutations invalidate that API's cached reads.

## Built-in API catalog

You don't need to hunt for spec URLs. `search_catalog` searches two sources:

1. A **curated list** of verified free/popular APIs: GitHub, GitLab, Stripe, OpenAI, Wikipedia, Open-Meteo (weather, no key), a countries GraphQL API, httpbin and the Swagger Petstore. Entries carry working spec URLs, base-URL overrides and auth hints (e.g. "optional GITHUB_TOKEN").
2. The [APIs.guru](https://apis.guru) directory - 2500+ community-indexed OpenAPI specs (Google, AWS, Microsoft, Twilio, NASA, ...), fetched once per session and searched locally.

```text
search_catalog(query="weather forecast")
  -> [{"name": "open_meteo", "spec": "https://...forecast.yml", "base_url": "https://api.open-meteo.com", ...}]
load_api(spec="https://...forecast.yml", name="open_meteo", base_url="https://api.open-meteo.com")
execute(operation_id="open_meteo.get_v1_forecast", params={"latitude": 52.52, "longitude": 13.41, "hourly": "temperature_2m"})
```

The catalog is discovery-only: it returns spec URLs, never loads or executes anything itself, so the security guard still applies to everything you load from it.

## Installation

The server runs in any MCP host via [`uvx`](https://docs.astral.sh/uv/) - no manual install needed, the package is fetched from [PyPI](https://pypi.org/project/universal-connector-mcp/) automatically (add `[all]` for GraphQL/gRPC/SOAP support):

```json
{
  "mcpServers": {
    "universal-connector": {
      "command": "uvx",
      "args": ["universal-connector-mcp"],
      "env": { "UCMCP_ALLOWED_HOSTS": "api.github.com" }
    }
  }
}
```

From source (development): `pip install -e ".[all,dev]"` and use `"command": "universal-connector-mcp"` instead. Extras: `graphql`, `grpc`, `soap`, `keyring`, `all`, `dev`; the core install supports OpenAPI/REST only.

### Cursor

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-black)](cursor://anysphere.cursor-deeplink/mcp/install?name=universal-connector&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ1bml2ZXJzYWwtY29ubmVjdG9yLW1jcCJdfQ==)

One click via the badge above, or add the JSON block to `.cursor/mcp.json` in your project (shared with your team) or `~/.cursor/mcp.json` (personal, all projects). See [`examples/mcp.json`](examples/mcp.json) for a full config with credentials.

### Claude Desktop

Add the same `mcpServers` block to `claude_desktop_config.json` (Settings > Developer > Edit Config).

### Claude Code

```bash
claude mcp add universal-connector -- uvx universal-connector-mcp
```

### VS Code (Copilot)

Add the server under `"servers"` in `.vscode/mcp.json`:

```json
{
  "servers": {
    "universal-connector": { "command": "uvx", "args": ["universal-connector-mcp"] }
  }
}
```

### Windsurf / Cline / others

All major MCP hosts accept the same `mcpServers` block shown above in their respective config files (`~/.codeium/windsurf/mcp_config.json`, Cline's MCP settings, etc.).

> AI agents installing this server for a user: follow [llms-install.md](llms-install.md).

### Preloading APIs

Point `UCMCP_APIS_CONFIG` at a YAML file to auto-load APIs at startup - see [`examples/apis.example.yaml`](examples/apis.example.yaml).

### Managing APIs from chat

You never edit config files to manage APIs - just tell your agent:

- *"Connect the Stripe API"* - the agent finds it in the catalog and loads it.
- *"What APIs are connected?"* - `list_apis` shows them.
- *"Forget GitHub"* - `unload_api` removes it (and from the remembered state).

When an API needs credentials, `load_api` tells the agent exactly which environment variable to set (e.g. `STRIPE_API_KEY`), whether it is already configured, and the agent relays copy-pasteable instructions - you add the variable to the `env` block of your MCP config and restart. Secrets are never typed into the chat.

### Session persistence

The server remembers which APIs you loaded (their spec locations - never credentials or response data) in `UCMCP_STATE_FILE` and restores them automatically on the next start, so the agent can pick up right where it left off. Set `UCMCP_STATE_FILE=off` to disable.

## Supported protocols

| Protocol | Spec source | Notes |
| --- | --- | --- |
| OpenAPI / Swagger | OpenAPI 3.x or Swagger 2.0 (JSON/YAML), URL/file/raw | Core install. Local `$ref` resolution, all HTTP methods. |
| GraphQL | I