Skip to content

DOCUMENTATION

OpenConnector clients: SDK, CLI, HTTP & MCP

Call an OpenConnector runtime with the TypeScript SDK, oo CLI, HTTP, or MCP, starting with a public Hacker News Action.

Maintained by OOMOL·

Source checked 2026-09-09. These examples were checked against the linked source revision. They are not a claim of live API verification; your deployed version may differ.

When to use OpenConnector

Use OpenConnector when an AI agent needs to call third-party services through authorized accounts, or when you need to control credentials and execution policies in your own infrastructure.

How to start

Choose a self-hosted or OOMOL-hosted runtime, connect an account, discover an Action, inspect its input schema and permissions, then make a small read-only call and check the result.

Runtime and API boundaries

This domain serves project information and documentation, not a live connector API or MCP server. Send calls to your chosen runtime. For self-hosting, inspect /openapi.json and /docs on that runtime. SaaS products connecting their own users’ accounts should follow the separate OOMOL product integration guide.

Product Integration Guide ↗

Install the official oo CLI

Install oo using the official installation guide, then use oo connector to discover and call Actions. Configure the runtime URL, runtime token and account connections for your chosen deployment.

Install the official oo CLI ↗

Official TypeScript SDK

Install @oomol-lab/connector from npm. Use OpenConnector for your own runtime; follow the OOMOL SDK guides for hosted personal accounts or SaaS end-user connections.

npm
npm install @oomol-lab/connector
npm: @oomol-lab/connector ↗

Runtime OpenAPI reference

Download the reference generated from a pinned runtime revision. Set runtimeUrl to your own deployment before using it. Provider-specific schemas come from that runtime’s catalog. This website does not execute API calls.

Runtime OpenAPI reference →Runtime source· 72de05b ↗

TypeScript

Install @oomol-lab/connector first. This example calls a running local OpenConnector instance from Node.js.

TypeScript
import { OpenConnector } from "@oomol-lab/connector";

const connector = new OpenConnector({
  baseUrl: "http://localhost:3000",
  runtimeToken: process.env.OOMOL_CONNECT_RUNTIME_TOKEN,
});

const stories = await connector.hackernews.get_top_stories({});
console.log(stories);

CLI

Install oo CLI, then point its connector commands at your local runtime. Authenticated deployments also require a runtime token.

CLI
oo connector login http://localhost:3000
oo connector search "Hacker News"
oo connector schema hackernews.get_top_stories
oo connector run hackernews --action get_top_stories --data '{}'

HTTP

Run this read-only, no-auth Action against a local runtime. Add your runtime bearer token if authentication is enabled.

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

MCP

Use this HTTP MCP endpoint in a compatible agent host. Follow the runtime API guide for client authentication and supported tools.

MCP
http://localhost:3000/mcp

Read the result

HTTP runtime responses use success, message, data and meta. Inspect success and the Action’s output schema, not just the HTTP status. When execution metadata includes executionId, use it to find the corresponding redacted run log. The example below illustrates the envelope; it is not a live API result.

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

If the call fails

  • For an authentication failure, check the endpoint and credential type: admin access protects /api; a runtime bearer token authorizes /v1 and /mcp. A provider API key is not a runtime token.
  • For a permission denial, check the Action’s required scopes, runtime Action rules and connection grants. A valid token may still be forbidden from using the selected account.
  • For empty or missing results, confirm the connected account and its access to the requested resource. Successful authorization does not grant access to every workspace, channel or document.
  • Inspect the error and run log before retrying. If an Action changes provider data, check whether it already completed; do not blindly repeat the request.
Read as Markdown