Using MCP with m9m

Model Context Protocol (MCP) is the missing API between LLMs and the tools they need. m9m ships an MCP server that exposes workflow-management primitives — list runs, start workflows, read logs, patch definitions, audit credential use — so an MCP-aware LLM can operate m9m itself. This guide walks through the tools, how to connect, and the patterns that make this useful rather than dangerous.

What m9m’s MCP server exposes

37 tools, grouped:

• Workflow management — workflow.list, workflow.get, workflow.create, workflow.update, workflow.delete, workflow.validate.
• Runs — run.start, run.cancel, run.retry, run.logs, run.artifacts, run.status.
• Nodes — node.list, node.describe, node.test.
• Credentials — credential.list, credential.describe (never credential.read_secret — the MCP surface never exposes secret values).
• Audit — audit.search, audit.stream.
• Triggers — trigger.list, trigger.test.
• Files — file.list, file.get, file.put (scoped to workflow run artifacts).
• Workspace — workspace.list, workspace.get.
• Plus schema-introspection tools for expression.eval, template.render, and similar.

Full list: m9m mcp tools on the command line.

How to start the server

m9m serve --mcp --mcp-port 8080
# or, over stdio for direct integration with Claude Code:
m9m mcp stdio

For Claude Code, add m9m to ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "m9m": {
      "command": "m9m",
      "args": ["mcp", "stdio"],
      "env": { "M9M_URL": "https://m9m.internal.example.com", "M9M_TOKEN": "..." }
    }
  }
}

Restart Claude Code; you should see m9m.* tools appear.

Typical patterns

Agent-as-SRE. An incident fires — a workflow is failing. You ask Claude Code:

“Find the workflow that’s failing in production. Read the error. Patch it and re-run.”

Behind the scenes the agent calls workflow.list → filters by status → run.logs → diagnoses → workflow.update → run.retry. Every action is audited; the workflow edit is a Git commit.

Agent-as-author. You describe a new workflow in English:

“Every morning at 9am, pull new GitHub issues tagged ‘support’ from repo X, summarise them with GPT-4, and post a digest to #support.”

The agent calls node.list → understands available node types → workflow.create with a draft → workflow.validate → iterates on errors → trigger.test → commits.

Agent-as-on-call. An agent monitors audit.stream for anomalies (unusual cost spikes, repeated failures, credential use spikes) and pages humans before the humans notice.

What we deliberately don’t expose

• Credential secret values — credential.describe returns metadata only. If the agent needs a secret, it uses credential.use to reference it in a workflow, never to read it.
• Host shell access — no exec or run_command tool. If you want the agent to run shell, it goes inside a sandboxed cli.* node inside a workflow.
• User management — the MCP surface is for workflows, not tenancy management. Users are managed via the admin UI and CLI.

Scoping and guardrails

Tokens are scoped by workspace. A token issued for the support workspace can only see support workflows. You can further restrict:

• Read-only tokens — for agents that observe but never edit.
• Dry-run mode — all workflow.update calls create PRs against the workflow Git repo, not live edits. Humans review and merge.
• Cost caps — per-token daily LLM-cost budgets (since an agent with MCP access is an LLM burning tokens).

These are the guardrails we recommend for any non-trivial deployment. An unscoped admin token and a capable model is a bad combination.

Debugging MCP interactions

Every MCP tool call is logged with inputs, outputs, duration, and the caller’s identity. m9m audit search mcp gives you the tape. For interactive debugging, m9m mcp inspect replays a tool call against a local m9m instance with verbose tracing.

If a tool doesn’t appear in your MCP client, check:

1. The client is actually connected (m9m mcp clients).
2. The token has access to the tool’s category (m9m mcp tools --token ...).
3. The client honours the server’s listChanged notification — some clients cache tool lists and need a restart to see newly-granted tools.

Related

• Agent core
• Article: agent orchestration with m9m
• For AI agent builders