@general-liquidity/mcp

A curated MCP server that projects the General Liquidity surface as seventeen task-shaped tools in four groups: money/identity, commerce, memory, and read-back. It is deliberately not a 1:1 dump of every REST endpoint, which would overrun an agent's token budget. The tool names are the surface verbs, and there is no settle or grant tool: settlement stays behind the client, and mandate granting is operator-only.

The server wraps a GeneralLiquidity client from @general-liquidity/sdk. The client is injected (dependency inversion): this package holds no settle primitive and no server implementation of its own. It signs and submits intents through the injected client; the sovereign gate decides and settles.

The tools

Money and identity:

• resolve — normalize any counterparty reference (A2A card, signed disclosure, CAIP) into one identity with its accepted rails and trust signals.

• pay — submit a signed Intent to move value. The gate decides; on allow it settles on the right rail and returns a Receipt.

• simulate — ask what the gate would decide, without doing any of it. Settles nothing, writes no audit entry, and does not consume the idempotency key, so simulating a payment never prevents making it. authorizes is always false: an allow here is an answer, not a grant.

• verify — check a counterparty's signed disclosure against policy and return a Decision.

• disclose — produce this agent's own signed disclosure: what it is and what it is authorized to do.

Commerce (the opt-in tier):

• quote — price a cart against a merchant over a checkout protocol (acp or ucp). Commits nothing and moves no money; returns the server-authoritative Cart the merchant priced. Only a Cart in status ready can then be bought.

• buy — drive that checkout to a completed Order, authorized through the same gate pay uses. The merchant stays merchant-of-record.

The price is never the caller's to set: it comes from the cart the merchant priced, which is why buy takes lines and no amount. Its replay key rides the body and must be supplied, because only a caller that chose its own key can safely re-send after a retryable rail failure. There is no parked-intent path — a merchant session cannot be held open across an out-of-band operator approval, so a gate confirm comes back as intent.denied, not approval.pending.

Both tools are registered on every server even though the tier is opt-in per deployment: a tool list whose shape depends on the stack is one a model cannot plan against. A deployment without the tier answers not_found, which arrives as the same structured problem as any other refusal.

Memory (bi-temporal, mandate-scoped):

• memory_remember — write one bi-temporal record under a mandate.

• memory_recall — read a sealed point-in-time snapshot, cursor-paginated.

• memory_assemble — assemble a budgeted, signed context.

• memory_verify — verify a signed memory artifact offline.

Read-back over the calling principal's own record:

• get_job — the lifecycle of one intent by its idempotency key.

• get_job_events — that intent's signed, hash-linked audit events.

• get_audit — the audit trail across every intent.

• list_intents — the caller's own intents, newest first, optionally narrowed to one status.

• get_mandate — the live spend authority covering the caller: caps, expiry, when the period resets, and how much of each has been drawn.

• get_usage — metered call counts over a window.

list_intents is the one to reach for holding an approval.pending problem whose intent id was not kept. A confirm verdict parks the intent and returns that id ONCE, so status: "pending" is how the parked payment is found again rather than paging the whole audit trail for something the agent cannot name. Each row carries the same lifecycle get_job returns, including the pending.challenge an operator approval binds to.

get_mandate is the one an agent should reach for BEFORE committing to anything metered or long-running, rather than discovering a ceiling by being refused. Its description carries a warning worth repeating here: spent and remaining are ABSENT together when the server holds a prior spend in a currency it cannot convert, which is the same state in which the gate refuses to authorize at all. Absent means unknown, never zero — the opposite reading has a model believe it holds its whole budget at exactly the moment it holds none.

What is deliberately absent

There is no approve, refund, kill switch, memory_forget or webhook CRUD tool. Those routes live in a disjoint authorization domain — the detached GL-Operator ed25519 credential — which the injected agent client cannot mint. Exposing them would either be dead weight or, worse, would let an agent release its own parked spend. An agent that can approve its own payment has no gate.

There is also no health tool, for a different reason: it would not work when it mattered. GET /health separates a deployment that is down from one that refused the credential, but an agent reaches this server over the same transport it would use to ask, so a stack that cannot answer cannot answer that either. The question belongs to the host process, and gl health answers it there.

Related MCP server: seashail

Structured failures

Every tool failure comes back as the same RFC 9457 problem the REST surface emits, on structuredContent, never as a thrown string:

{
  "code": "intent.denied",
  "message": "The gate denied intent idem-1.",
  "action": "escalate-to-human",
  "data": {
    "type": "https://docs.generalliquidity.com/problems/intent.denied",
    "status": 403,
    "action": "escalate-to-human",
    "nextStep": "Stop. A human operator must decide; no retry helps.",
    "retryable": false,
    "reasons": ["payee not on the mandate"]
  }
}

Branch on action, not on code: codes are added over time, while the four action classes (never-retry, retry-as-is, retry-after-renegotiation, escalate-to-human) are closed. A confirm verdict is one of these problems (approval.pending) and carries the parked intent id and challenge an operator needs to release it out-of-band.

Two codes now share 429 and mean opposite things, which is the sharpest reason to branch on action. rate_limited is retry-as-is and clears in seconds. quota_exceeded is escalate-to-human: the plan's call allowance is spent, and an agent can no more buy itself a larger plan than approve its own parked payment. A client keyed on the status alone waits out a billing period for something an operator clears in a minute.

The taxonomy in src/problem.ts mirrors the platform's @general-liquidity/surface vocabulary, which is an unpublished workspace package this repository cannot import. src/results.ts also bridges the SDK's own legacy error slugs (denied, rate-limited, validation) onto it, so an older peer still speaks the shared codes.

Adding it to an agent host

createMcpServer returns an unconnected McpServer. You wire the client and a transport (stdio / HTTP) at your composition root:

import { createMcpServer } from "@general-liquidity/mcp";
import { createClient } from "@general-liquidity/sdk";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const client = createClient({ baseUrl, signer }); // any GeneralLiquidity impl
const server = createMcpServer(client, { name: "gl", version: "1.0.0" });

await server.connect(new StdioServerTransport());

Point your agent host (Claude Desktop, an IDE MCP client, or any stdio MCP host) at the process running that entry point.

What it exports

• createMcpServer / McpServerOptions — build the curated MCP server over an injected client.

• buildTools / ToolDef / ToolResult — the tool set and its call-result shape, exported separately so tests can assert registration and delegation with a fake client and no transport.

• TOOL_NAMES / COMMERCE_TOOL_NAMES / MEMORY_TOOL_NAMES / READ_TOOL_NAMES / ALL_TOOL_NAMES — the exposed tool names, by group.

• problem / actionFor / nextStep / isRetryable / requiresHuman / ALL_PROBLEM_CODES and the Problem, ProblemCode, ErrorAction, StructuredError types — the shared failure taxonomy.

Dependencies

• @general-liquidity/sdk — supplies the GeneralLiquidity client type and the wire nouns (Intent, Disclosure, Counterparty, Receipt, Decision).

• @modelcontextprotocol/sdk — the MCP McpServer.

• zod — tool input schemas.

Development

bun install
bunx tsc --noEmit -p tsconfig.json
bun test
bunx biome check .