runtime-api.md

Runtime API And MCP

OpenConnector exposes provider Actions through MCP, HTTP, OpenAPI, local Action guides, and the Web Console. This document is the detailed reference that keeps endpoint lists and protocol examples out of the README.

Access Surfaces

Surface	Endpoint	Use it for
MCP	POST /mcp	Agent hosts that can call MCP tools.
MCP metadata	GET /mcp/tools	Preview the discovery-oriented MCP tool set.
HTTP runtime API	/v1/*	SDK-style clients, scripts, and direct Action execution.
OpenAPI	GET /openapi.json	API importers, reference generation, and strongly scoped one-Action specs.
Action guide	GET /api/actions/:actionId/agent.md	Agent-readable markdown guide for one Action.
Web Console	GET /	Browser workflow for browsing providers, configuring credentials, and debugging Actions.

When OOMOL_CONNECT_RUNTIME_TOKEN or persistent runtime tokens are configured, /v1/* and /mcp callers should send:

Authorization: Bearer oct_...

Admin endpoints under /api/*, /docs, and the Web Console use OOMOL_CONNECT_ADMIN_TOKEN when it is configured.

MCP

Point MCP-capable clients at:

http://localhost:3000/mcp

The MCP server exposes a small discovery-oriented tool set:

• list_apps
• search_actions
• get_action_guide
• execute_action

Preview MCP tool metadata:

curl -s http://localhost:3000/mcp/tools

HTTP Runtime API

Runtime clients should use /v1. Responses use a uniform JSON envelope:

{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

Discover Actions:

curl -s http://localhost:3000/v1/actions
curl -s "http://localhost:3000/v1/actions?service=github"
curl -s http://localhost:3000/v1/actions/github.get_current_user

Execute an Action:

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Select a named connection with x-oo-connector-alias:

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

The alias query parameter is also accepted:

curl -s -X POST "http://localhost:3000/v1/actions/github.get_current_user?alias=work" \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Action Guides

Each Action has a local markdown guide that includes the input schema, scopes, provider permissions, current connection identity, and request examples:

curl -s http://localhost:3000/api/actions/github.get_current_user/agent.md

The Web Console also lets you copy cURL, TypeScript, and agent prompt examples for each Action.

Transit Files

Upload a temporary local transit file for Actions that accept a file URL:

curl -s -X POST http://localhost:3000/api/files \
  -F "file=@./report.pdf"

The response includes a downloadUrl under /api/files/:fileId. Local transit files are stored under OOMOL_CONNECT_DATA_DIR/files and are cleaned up by age.

Public Runtime Endpoints

• GET /v1/health
• GET /v1/providers
• GET /v1/actions
• GET /v1/actions/search
• GET /v1/actions?service=<service>
• GET /v1/actions/:actionId
• POST /v1/actions/:actionId
• GET /v1/apps
• GET /v1/apps/services/:service
• GET /v1/apps/authenticated
• POST /v1/proxy/:service

POST /v1/proxy/:service currently returns proxy_not_supported until a provider proxy runtime is implemented.

Local Admin Endpoints

These endpoints power the Web Console, examples, and setup scripts:

• GET /api/providers
• GET /api/providers/:service
• GET /api/actions
• GET /api/actions/search
• GET /api/actions/:actionId
• GET /api/actions/:actionId/agent.md
• POST /api/files
• GET /api/files/:fileId
• DELETE /api/files/:fileId
• GET /api/connections
• PUT /api/connections/:service
• DELETE /api/connections/:service
• GET /api/oauth/configs
• PUT /api/oauth/configs/:service
• DELETE /api/oauth/configs/:service
• POST /api/oauth/authorizations
• GET /oauth/callback
• GET /api/runtime-tokens
• POST /api/runtime-tokens
• DELETE /api/runtime-tokens/:id
• GET /api/runs
• POST /mcp
• GET /mcp/tools
• GET /openapi.json