Skip to main content
Glama

@multiagentcoordinationprotocol/mcp

An MCP server that lets any MCP client (Claude Desktop, Claude Code, Cursor and others) run or join a MACP Decision session. It is the TypeScript twin of the Python macp-mcp. Both expose the same tool surface: the same names, input schemas and outputs, pinned by one shared manifest (Tool contract). Package versions are independent of the Python macp-mcp; tool parity is enforced by make verify-contract, not by matching version numbers.

MCP decides which tools a model can call. MACP decides who may use them and when, and records what was decided. The model drives every step through ordinary MCP tool calls. The MACP runtime enforces who may propose, vote and commit, ends the session in one binding Commitment, and gives that outcome an RFC-MACP-0013 hash that anyone can recompute.

MCP client (model) ──stdio──▶ macp-mcp ──gRPC──▶ MACP runtime
   tool calls                 one MACP agent       enforces membership, order,
                              (macp-sdk-typescript) identity; records the Commitment

Install

npx -y @multiagentcoordinationprotocol/mcp     # or: npm i -g @multiagentcoordinationprotocol/mcp

Node 20 or newer. The installed binary is called macp-mcp, like the Python server's. It needs a MACP runtime to talk to. For local development:

docker run -p 50051:50051 -e MACP_ALLOW_INSECURE=1 -e MACP_MEMORY_ONLY=1 \
  ghcr.io/multiagentcoordinationprotocol/macp-runtime:0.14.1

One macp-mcp process is one MACP agent. For several agents to take part in a session, run one server per agent (for example, one per MCP client), each with its own MACP_AGENT_ID.

Related MCP server: eidolon-gateway

Configure your MCP client

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "macp": {
      "command": "npx",
      "args": ["-y", "@multiagentcoordinationprotocol/mcp"],
      "env": {
        "MACP_RUNTIME_TARGET": "127.0.0.1:50051",
        "MACP_AGENT_ID": "coordinator",
        "MACP_ALLOW_INSECURE": "1"
      }
    }
  }
}

Claude Code

claude mcp add macp \
  --env MACP_RUNTIME_TARGET=127.0.0.1:50051 \
  --env MACP_AGENT_ID=coordinator \
  --env MACP_ALLOW_INSECURE=1 \
  -- npx -y @multiagentcoordinationprotocol/mcp

Then ask the model something like: "Start a MACP decision with alice on which deployment plan to use, propose a canary rollout, and vote for it."

Against a production runtime

Drop MACP_ALLOW_INSECURE and pass the bearer token the runtime issued for this agent:

"env": {
  "MACP_RUNTIME_TARGET": "macp.example.com:443",
  "MACP_AGENT_ID": "coordinator",
  "MACP_AUTH_TOKEN": "<token issued for coordinator>"
}

Environment variables

These are the same variables, with the same defaults, as the Python server.

Variable

Default

Meaning

MACP_RUNTIME_TARGET

127.0.0.1:50051

Runtime gRPC address (host:port).

MACP_AGENT_ID

mcp-agent

The MACP agent this server acts as. With dev-agent auth it is also the bearer token. With MACP_AUTH_TOKEN it is the identity the runtime must bind the token to.

MACP_AUTH_TOKEN

unset

Bearer token issued by the runtime. When unset, dev-agent auth is used, which needs a runtime started with MACP_ALLOW_INSECURE=1.

MACP_ALLOW_INSECURE

off

1/true/yes/on uses plaintext gRPC. For a local runtime only.

MACP_TLS_CA_FILE

system trust

PEM bundle for a private CA. Cannot be combined with MACP_ALLOW_INSECURE.

MACP_DEFAULT_TTL_MS

300000

Session TTL used when start_session is called without ttl_ms.

MACP_REPLAY_IDLE_MS

1000

How long a history read waits for the next envelope before treating the replay as complete.

The server logs to stderr only, because stdout carries the MCP protocol. A bad configuration exits with status 2 and a one-line message.

Tools

Tool

Kind

What it does

start_session

write

Start a Decision session with this agent as initiator. Takes intent, participants and optional ttl_ms and context_id. Returns the session_id to share.

propose

write

Put an option (proposal_id, option, rationale) up for decision.

evaluate

write

Record a scored assessment (APPROVE / REVIEW / BLOCK / REJECT, confidence 0..1) before voting.

vote

write

Cast this agent's APPROVE / REJECT / ABSTAIN vote on a proposal.

commit

write

Resolve the session with a binding Commitment (action, authority_scope, reason). Under the default policy only the initiator can commit.

get_session

read

The session's state, participants, proposals, evaluations, votes, approve totals and majority winner.

get_commitment

read

The resolved session's binding Commitment, the exact payload bytes (payload_b64) and its RFC-MACP-0013 commitment_hash.

verify

read

Recompute a commitment hash with the SDK verifier, either from the runtime's recorded history (session_id) or from bytes you hold (payload_b64). Returns match, mismatch or cannot_verify.

Errors the model can act on, such as a runtime rejection or a bad argument, come back as tool errors with the text "<CODE>: <message>", for example FORBIDDEN: Forbidden when a non-initiator tries to commit. The code is the MACP error code: the Ack failure code, then the macp-error-code trailer, then the gRPC status name.

The server is stateless. Every read replays the session from the runtime, so a restart loses nothing, and several servers (agents) can share one session.

Gate upstream tool calls (macp-mcp gate)

macp-mcp gate is a second mode of the same binary. It runs as an MCP server in front of another (upstream) MCP server, and puts the tool calls you name behind a MACP session: a matching call reaches the upstream only after a Quorum or Decision session commits approve. Every other call passes straight through.

macp-mcp gate --policy gate.json --upstream npx -y @modelcontextprotocol/server-filesystem /srv/data

--upstream takes the rest of the command line as the upstream's stdio command. The gate uses the same environment variables as the base server (MACP_AGENT_ID is the gate's identity: it initiates and commits every session). The upstream inherits the gate's environment minus MACP_AUTH_TOKEN, so the gate's credential never reaches it.

gate.json names the rules; the first rule whose tool matches wins (exact name, or a glob with * and ?):

{
  "version": 1,
  "server": "filesystem",
  "rules": [
    { "tool": "write_*", "mode": "macp.mode.quorum.v1", "participants": ["alice", "bob", "carol"], "threshold": 2 },
    { "tool": "move_file", "mode": "macp.mode.decision.v1", "participants": ["alice", "bob"], "ttl_ms": 60000 }
  ]
}

Field

Meaning

server

The upstream's name, bound into every gated call's context_id.

tool

Exact tool name or glob.

mode

macp.mode.quorum.v1 (ApprovalRequest + ballots) or macp.mode.decision.v1 (Proposal + votes).

participants

The approvers. Must not include the gate's own agent id.

threshold

APPROVE ballots needed, in either mode. Default: a strict majority of participants.

ttl_ms

Session TTL. Default 300000.

policy_version

Optional RFC-MACP-0012 policy to bind the session to, for example one of the spec's policy packs.

For a gated call the gate:

  1. Starts a session whose context_id is sha256: + the hex SHA-256 of the RFC 8785 (JCS) form of {"arguments", "server", "tool"}. The same canonical JSON travels in the ApprovalRequest details (Quorum) or the Proposal rationale (Decision), so an approver can recompute the binding.

  2. Commits approve as soon as the approvers' latest ballots reach the threshold, or deny as soon as they no longer can (REJECT and ABSTAIN both count as not-approve).

  3. On approve, forwards the call and adds the commitment to the result, beside any _meta the upstream set:

    "_meta": {
      "io.multiagentcoordinationprotocol/commitment": {
        "session_id": "…", "mode": "macp.mode.quorum.v1", "outcome": "approve",
        "commitment_hash": "sha256:…"
      }
    }

    commitment_hash is the RFC-MACP-0013 hash; the base server's verify tool recomputes it from the runtime's history.

  4. Otherwise refuses with a tool error, and never calls the upstream: POLICY_DENIED: … when the session commits deny (or a bound policy refuses the commitment), SESSION_NOT_OPEN: … when the session expires or is cancelled without a commitment. If the session is still open 5 s after its TTL, the gate cancels it. A call whose arguments hold an integer outside ±(2^53−1) is refused with INVALID_ARGUMENT: … before any session opens: JSON may already have rounded it, so it has no canonical form.

Approvers are ordinary MACP agents, for example a base macp-mcp server driven by a person or another model, voting through the runtime. See examples/gated-tool-call.md for a full transcript. The policy schema, CLI flags, wire values and context_id test vectors live in contract/gate/, byte-identical to the Python macp-mcp's.

Binding a runtime policy (policy_version)

A rule can bind the session, through policy_version, to an RFC-MACP-0012 policy registered on the runtime. Set the rule's threshold to at least the bound policy's threshold. The gate commits on its own tally, so with a lower rule threshold it commits early and the runtime refuses the Commitment:

  • Decision: the refusal is POLICY_DENIED: <runtime message>.

  • Quorum: macp-runtime 0.14.0 applies a policy threshold inside the mode's commitment-readiness check, so the refusal is INVALID_ENVELOPE (an invalid payload), not POLICY_DENIED.

In both modes the gate fails safe. The call is refused after the first approval, the upstream is never called, and the gate cancels the session (CANCELLED). The note under policy_binding in contract/gate/session.json records the same behaviour. Integration tests pin it against runtime 0.14.0: tests/integration/gate-policy.test.ts (added in #10) and the Python macp-mcp's test_gate_policy.py (#12).

Tool contract

contract/tools.json pins the tool names, descriptions, annotations, input schemas and output schemas as fully inlined JSON Schema 2020-12. The Python macp-mcp generates it, and this repo keeps a byte-identical copy. This server does not derive its schemas from code: it serves the manifest verbatim from tools/list and validates every call's arguments against it with Ajv, so the advertised surface cannot drift from the file. The file also ships in the npm package as @multiagentcoordinationprotocol/mcp/contract/tools.json.

The gate's contract (contract/gate/) is vendored the same way. CI fails if any of these files drifts from the Python repo's (make verify-contract). After a deliberate surface change lands in macp-mcp, run make sync-contract and implement the change here.

Library use

The package also exports the pieces, for embedding the server in another process or testing against it:

import { buildServer, loadSettings } from '@multiagentcoordinationprotocol/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const { server } = buildServer({ settings: loadSettings() });
await server.connect(new StdioServerTransport());

Development

npm ci
npm run check && npm run lint && npm run format:check
npm test                   # unit tests (fake runtime, in-memory MCP client)
make verify-contract       # contract/tools.json == the Python macp-mcp's

# Acceptance: two stdio MCP clients drive a Decision session to RESOLVED
docker run -d --rm --name macp-runtime-test -p 50051:50051 \
  -e MACP_BIND_ADDR=0.0.0.0:50051 -e MACP_ALLOW_INSECURE=1 -e MACP_MEMORY_ONLY=1 \
  ghcr.io/multiagentcoordinationprotocol/macp-runtime:0.14.1
npx tsx scripts/wait-for-runtime.ts
npm run test:integration

Releases follow macp-sdk-typescript: release-please opens the release PR, and merging it creates the GitHub release, which publishes to npmjs with provenance.

License

Apache-2.0

Available Tools

8 tools
commitA

Resolve the session with a binding Commitment (normally the initiator).

After this the session is RESOLVED and accepts no further messages.

Inputs: action (required), reason (required), session_id (required), authority_scope (required), +1 more. Returns: ok, sender, duplicate, message_id, +2 more

evaluateB

Record a scored assessment of a proposal before voting (optional step).

Inputs: confidence (required), session_id (required), proposal_id (required), recommendation (required), +1 more. Returns: ok, sender, duplicate, message_id, +3 more

get_commitmentA
Read-onlyIdempotent

Return a resolved session's binding Commitment and its RFC-MACP-0013 hash.

found is false while the session is still open. payload_b64 is the exact Commitment payload bytes the runtime recorded; commitment_hash is computed over them.

Inputs: session_id (required). Returns: found, state, sender, commitment, +5 more

get_sessionA
Read-onlyIdempotent

Show a session's state, participants, proposals, evaluations, votes and winner.

Reads the runtime's session history, so it includes every participant's messages.

Inputs: session_id (required). Returns: you, mode, phase, state, +17 more

proposeC

Put an option up for decision in a session.

Inputs: option (required), session_id (required), proposal_id (required), rationale. Returns: ok, sender, duplicate, message_id, +3 more

start_sessionA

Start a new MACP Decision session with this agent as initiator.

Returns the new session_id; share it with the other participants so they can join.

Inputs: intent (required), participants (required), ttl_ms, context_id. Returns: ok, mode, ttl_ms, duplicate, +5 more

verifyA
Read-onlyIdempotent

Check a commitment hash by recomputing it (RFC-MACP-0013).

Pass exactly one of session_id or payload_b64. outcome is match, mismatch, or cannot_verify (the payload itself is not hashable under the label).

Inputs: commitment_hash (required), session_id, payload_b64. Returns: source, outcome, hash_label, session_id, +2 more

voteA

Cast this agent's vote on a proposal. One vote per agent per proposal.

Inputs: vote (required), session_id (required), proposal_id (required), reason. Returns: ok, vote, sender, duplicate, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    Each tool maps to a distinct step in the decision lifecycle (start, propose, evaluate, vote, commit) plus read-side tools (get_session, get_commitment, verify). The boundary between commit, get_commitment, and verify is slightly subtle—all involve commitments—but descriptions clarify that one writes, one retrieves, and one recomputes a hash. One or two tools could still be momentarily confused by an agent skimming names.

    Naming Consistency4/5

    The set uses verb-based names throughout, split between bare verbs (commit, evaluate, propose, verify, vote) and get_-prefixed reads (get_session, get_commitment). This is a coherent and readable convention, with the get_ prefix sensibly marking read-only operations. Minor deviation from a strict verb_noun pattern keeps it from a 5.

    Tool Count5/5

    Eight tools is well-scoped for a decision protocol covering initiate, propose, evaluate, vote, commit, and audit. Every tool corresponds to a real step or verifiable artifact, with no redundancy or filler.

    Completeness3/5

    The write/read lifecycle is largely covered, but start_session instructs the initiator to share the session_id so others can join, yet no join_session tool exists—an apparent dead end for non-initiator participants. There is also no way to list or discover active sessions, which limits usability in multi-party flows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables transparent MCP proxying with a hash-chained effect ledger, classifying agent actions by reversibility, enforcing approval gates, and dry-run previews of sessions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to govern downstream tool servers by enforcing default-deny authority and attestation on every tool call, with live monitoring, approval, and mid-session revocation.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides a policy-controlled MCP gateway that lets agents invoke tools with explicit policies, bounded execution, scoped visibility, and decision receipts.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-speaking agents to execute tool calls through an authorization gate, producing signed decision records and reconciled effect rows for accountability.
      6
      Apache 2.0