Connectors & MCP

How integrations reach your agents — OAuth/API-key connectors and MCP servers over HTTP or stdio.

Nodal-Agents gives agents access to external services through two complementary mechanisms: Connectors and MCP servers. Both are assigned per agent; neither changes the runner's generic architecture — the agent's tool whitelist is computed from its assigned integrations at job-start time.

Connectors

A connector is a first-party integration backed by a dedicated adapter in the runner. The connector catalog lists every integration the runner knows how to talk to. Adding a connector from the catalog guarantees the adapter ships with it — no connector is exposed without a working implementation.

Auth types

Auth type	How you connect
OAuth 2	Click "Connect" in the dashboard; an OAuth flow authorizes the integration. One Google credential backs Drive, Gmail, Sheets, and Docs simultaneously.
API key	Paste a key or Personal Access Token.

Available connectors

Fifteen connectors ship in the catalog:

Name	Auth
Notion	API key
Notion (OAuth)	OAuth 2
Google Drive	OAuth 2 (`google-oauth`)
Gmail	OAuth 2 (`google-oauth`)
Google Calendar	OAuth 2 (`google-oauth`)
Google Sheets	OAuth 2 (`google-oauth`)
Google Docs	OAuth 2 (`google-oauth`)
Outlook Mail	OAuth 2 (`microsoft-oauth`)
Airtable (OAuth)	OAuth 2
Airtable	API key (Personal Access Token)
Apify	API key
Cloudflare	API key
Firecrawl	API key
Tavily	API key
Poyo	API key

The connectors reference is generated from the catalog itself, one page per connector, with the full tool inventory grouped by risk and the exact OAuth scopes each one requests.

Assign a connector to an agent

Go to API Connectors in the dashboard and connect the integration (OAuth flow or paste a key).
Open the target agent's edit page and go to the Connectors tab.
Enable the integration. Its tools become available on the agent's next job.

The Connectors tab also carries an enabled-operations allowlist per connector: destructive operations (delete, overwrite) can be switched off for one agent while the rest of the connector stays available. Every connector page in the reference marks which of its tools are destructive.

Credentials are fetched from the database at execution time — they are never baked into a job at enqueue time.

MCP servers

MCP (Model Context Protocol) servers expose tools that the runner discovers at job-start and injects into the agent's whitelist. Tools are namespaced with the server's slug to avoid collisions: a server with slug stripe exposes tools like stripe__retrieve_balance.

The catalog carries 24 ready-made servers plus two "add your own" entries, one HTTP and one stdio. Each has its own generated page with transport, auth and setup.

Transports

Nodal-Agents supports two transports:

HTTP (Streamable HTTP) — a hosted server reachable over HTTPS. The runner connects, authenticates (header, query-param, or Bearer token), and calls tools/list. Examples: Stripe, Airtable (hosted), Cogni Cortex, Composio.

stdio — a local subprocess spawned by the runner on first use. The runner executes the command (typically npx -y <package>) and communicates via stdin/stdout. The subprocess is torn down after the job. Examples: Filesystem, Git, GitHub, PostgreSQL, Playwright.

For stdio servers that use npx, the package is downloaded on first use (requires network; expect 5–30 s latency on the initial connection; subsequent runs use the npx cache).

Auth

HTTP servers authenticate with a static key. How the key is injected depends on the server:

header — sent as a named request header (e.g. x-api-key: <key>)
bearer — sent as Authorization: Bearer <key>
query — appended to the URL as a query parameter

stdio servers use environment variables instead of HTTP auth. Env var values are encrypted at rest.

Tool risk levels

The runner maps MCP tool annotations to its own risk model:

MCP annotation	Risk level
`readOnlyHint: true`	`read` (autonomous, no approval gate)
`destructiveHint: true`	`destructive`
no annotation	`write` (conservative default — passes through the approval gate)

Adding an MCP server

From the catalog:

Go to MCP Connectors in the dashboard (the Agents board, under Connect).
Pick a server from the library (verified or pending badge) and click Connect.
Fill in the URL (if required), API key, and any env vars shown.
Open the target agent's edit page → Connectors tab → enable the MCP server.

Custom HTTP server:

Select "Custom MCP (HTTP)" in the catalog. Provide a short slug (becomes the tool-name prefix), the server URL, and auth details.

Custom stdio server:

Select "Custom MCP (stdio)". Provide a slug, the executable command (e.g. npx), args, and any required env vars. The runner spawns it with your permissions — only connect servers you trust.

Catalog status badges

Verified — tested end-to-end against a live server.
Test pending — shipped but not yet live-verified. Connection parameters may need adjustment.

Nodal as an MCP server

The direction also works in reverse: Nodal can expose itself as an MCP server, so an external client — your terminal, a coding agent like Claude Code — hands work to your agents instead of the other way around.

Enable the MCP server switch in Settings → Safety (off by default). The same section then gives, for the machine that hosts Nodal:

Claude Code: the exact command to run. It is built from the Node and the script that started this install, so it works whether Nodal was installed globally, launched with npx, or run from source. Its shape:
```
claude mcp add nodal -- "<path to node>" "<path to the nodal-agents CLI>" mcp serve
```
Claude Desktop: the mcpServers entry for its configuration file, and an Add to Claude Desktop button that writes it for you. The button keeps your other servers and saves a copy of the previous file first.

Both clients can be connected at the same time; their runs land on the same page. If the section asks you to start Nodal with nodal-agents up, the web was started some other way and does not know the command: it shows none rather than a guess.

The client gets exactly one tool, run_task: it creates a tracked job for your workspace's root agent (or a chosen agent by slug) and returns the job id immediately. The work itself runs asynchronously through the normal loop — the agent's own tools, approval rules, budgets, and delegation.

Nobody typed these runs, so they have no conversation: they land in their own MCP folder under Channels, whose rows open the run page directly, and they appear in Logs → Activity like any other run.

What the door never grants, whatever the switch says: the configuration tools. An MCP job can ask for work; it cannot create agents, skills, connectors or automations — that is enforced in the runner. At most 5 MCP jobs of a workspace run at the same time, whichever client or server process started them: a sixth is refused with the list of the running ones, and a job that finishes frees its place. What a job may spend is bounded by its agent's own budget. Turning the switch off cuts clients that are already connected — the server re-checks it on every call.

How tools reach the agent

At job-start the runner fetches the agent's assigned connectors and MCP servers from the database, opens connections, calls tools/list on each MCP server, and builds the complete tool whitelist for that job. The agent only sees tools it has access to — there are no implicit defaults.

See Agents for the full picture of how a job runs.

Connectors & MCP

On this page