Skip to main content
Modulo

MCP

Modulo serves a Remote Model Context Protocol (MCP) server at /mcp on your own instance. An MCP client authenticates with a Bearer credential and works against the same governed surface as the web app: list and read pipelines, trigger runs, read run status and output, browse the library, review human-in-the-loop gates, and manage pipelines, triggers, and schemas. MCP is included in the free Community tier.

Server URL and configuration snippets

Settings > MCP shows the server URL together with configuration snippets you can paste into your client. Snippets are provided for opencode / Claude Code, Claude Desktop, Cursor, Continue.dev, and a custom client.

The server URL is your MODULO_PUBLIC_URL with the /mcp path appended. When MODULO_PUBLIC_URL is unset, the page falls back to http://localhost:8000/mcp. See Configuration.

Authentication

Every MCP request carries a Bearer credential, and Modulo accepts two kinds:

  • MCP API key (prefix mk_), created and revoked at Settings > MCP with an operator or runner role. A key is organization-scoped by default and can be narrowed to a single team. The user_scoped_mcp_keys organization flag adds per-user keys that act as their creator’s identity.
  • OAuth 2.0 access token, issued to an OAuth client application registered for your organization by an admin or an operator. Register one in the Registered OAuth Clients card at Settings > MCP with Register OAuth Client. The form asks for a client name, one or more redirect URIs, and at least one of the three valid scopes: trigger:run (trigger pipeline runs), hitl:review (claim and decide human-in-the-loop gates), and library:browse (browse the library).
    • Each redirect URI must be an absolute http:// or https:// address. Loopback addresses such as http://127.0.0.1:5173/callback are allowed for local development.
    • Modulo shows the client secret once, in the dialog that opens when the client is created, and never shows it again. Copy it immediately; register the client again if it is lost.
    • The consent screen is a browser route at /oauth/authorize. It is the redirect target of the MCP protocol endpoint GET /mcp/oauth/authorize; the token endpoints POST /mcp/oauth/token and POST /mcp/oauth/refresh also sit on the MCP server. An anonymous visitor can reach the consent screen and sign in there before approving, so the authenticated approve call is itself the consent record.
    • Registering an OAuth client requires MODULO_PUBLIC_URL to be configured.

A requested scope the client is not registered for is refused, and scopes are re-checked on every call rather than only at issue. A token’s granted authority can never exceed the account’s live role: a hitl:review scope needs operator, everything else needs runner, and an account demoted after the token was issued drops to its new role on the next call.

Human-linked credentials

Modulo separates a credential that belongs to a human account from one that belongs to a machine. The distinction matters for human-only gates, where the question is not only whether a credential may act, but whose authority the decision carries.

  • Human-linked. A consent-derived OAuth 2.0 access token issued to a member of your organization. The token is tied to that person’s account, so a decision made with it counts as that person’s decision.
  • Machine. An MCP API key (mk_), including a per-user key, or any credential belonging to a service account. A machine credential can operate pipelines, but it cannot decide a human-only gate.

Use a human-linked token only in a client you are driving yourself, on your own machine, such as opencode, Claude Code, or Cursor. Never put one into a cloud agent, a pipeline, a shared continuous integration (CI) job, or anything that acts while you are away. An agent that runs unattended should authenticate with an organization or machine credential, and if it needs to reach a human-only gate, that is the signal the gate should be decided by a person rather than delegated to the agent.

Approving a human-only gate with your own token is you approving it. The audit record attributes the decision to the human whose token it was, not to the agent or to Modulo. An organization can turn human-linked MCP authority off, which restores the stricter behavior where no MCP credential can decide a human-only gate.

A human-linked credential tells you whose account a decision belongs to. It does not prove the person was present when the decision was made, because a token can be copied. Treat it as that person’s stated authority, not as evidence they were at the keyboard.

Tools

Tools cover the whole operator surface, grouped by area:

  • Pipelines: list, read the graph, create, update, and delete pipelines, plus connector binding on a node.
  • Runs: trigger a pipeline, read run status, read a node’s output, read eval results, list runs, and cancel a run.
  • Human-in-the-loop: list pending gates, read a gate with its captured configuration, and claim or decide a gate with review_hitl.
  • Triggers and schemas: create, read, update, and delete triggers; list and create schemas; validate a payload against one.
  • Library: search the library and copy a primitive into your workspace.
  • Documentation: search this documentation set.

Each tool is authorized against your key’s role, so a runner key can do less than an operator key.

Resources

Alongside tools, the server exposes resources under modulo:// URIs, including modulo://pipelines, modulo://pipelines/{pipeline_id}, modulo://runs/{run_id}, modulo://schemas, modulo://connectors, modulo://model-backends, modulo://library, and modulo://library/{primitive_type}/{slug}. Listing resources returns these URIs; reading one returns the rendered content.

Governance and safety

  • Authorization mirrors the REST API. Every tool maps to a permission in the same registry the REST routes use, and your key’s role must hold it. A pipeline node that declares an allowed_tools allow-list is further limited to those tools for the whole request.
  • Human-only gates need a human-linked credential. A gate marked human-only can be claimed and decided through MCP only by a credential linked to a human account, as described under Human-linked credentials. An MCP API key and any service-account credential are refused. Manually delivering a gate’s output stays browser-only. Every decision and every denial is recorded in the audit log.
  • Rate limits apply per client. All /mcp traffic is limited to 200 requests per minute, trigger_pipeline to 60 per minute, and human-in-the-loop decision actions to 20 per minute.
Next: Kubernetes