MCP reference
Mint MCP is a stateless, stdio JSON-RPC server. It reads declarations and audit records. It never resolves a secret or swaps a placeholder. Credentialed effects use the Mint HTTP proxy, not MCP. See the HTTP API reference for that route.
Start the server
Section titled “Start the server”The binary is mint-mcp. It reads one JSON object per input line. It writes one JSON object per response line.
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | mint-mcpBlank lines are ignored. The server flushes each response line. Malformed JSON is logged to stderr and does not produce a JSON-RPC response. A notification without an id produces no response.
The server re-reads each requested file from disk. It does not open a secret store or an HTTP client.
JSON-RPC methods
Section titled “JSON-RPC methods”Mint handles these protocol methods:
| Method | Result |
|---|---|
| initialize | Reports the requested protocol version, server name, version, and tool capability. |
| tools/list | Returns the exactly four tool definitions. |
| tools/call | Dispatches one of the four tool names. |
| ping | Returns an empty object. |
An unknown method returns a JSON-RPC error with code -32603. An unknown tool returns the same error code.
MCP exposes exactly these four read-only tools. No tool resolves, returns, or forwards credential bytes.
alias_list
Section titled “alias_list”List alias declarations.
Input schema:
{"type":"object","properties":{"path":{"type":"string"}}}The optional path overrides MINT_ALIASES_PATH. The default path is .mint/aliases.yaml.
{"path":"./examples/aliases.yaml"}The result contains path, count, and aliases. Alias values are descriptive names and descriptions. Mint does not resolve any alias.
policy_check
Section titled “policy_check”Parse and validate one policy file.
Input schema:
{"type":"object","required":["file"],"properties":{"file":{"type":"string"}}}The file argument must be a non-empty string.
{"file":"./examples/policy.yaml"}The result contains file, valid, rule_count, legacy_call_limit_count, and default. A load or validation error becomes a JSON-RPC tool error.
audit_tail
Section titled “audit_tail”Read recent audit events.
Input schema:
{"type":"object","properties":{"n":{"type":"integer","minimum":1},"path":{"type":"string"}}}Omit n to read the default 20 events. The optional path overrides MINT_AUDIT_LOG_PATH. The default path is .mint/audit.log.
{"n":10,"path":"./examples/audit.log"}The result contains path, count, and events. Events are read-only audit records.
mint_usage
Section titled “mint_usage”Explain the credentialed HTTP path.
The input object has no fields.
{}The result documents the proxy route, capability header, placeholder syntax, and read-only tool names. It contains no credential material.
Calling a tool
Section titled “Calling a tool”Send tools/call with a tool name and arguments.
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"policy_check","arguments":{"file":"./examples/policy.yaml"}}}A successful call returns a content array with one text block. The text block contains pretty-printed JSON for the tool payload. A failed call returns a JSON-RPC error object.
Credentialed requests must use the authenticated HTTP route. MCP cannot issue, resolve, or inject a capability.
Source map
Section titled “Source map”The stdio loop, blank-line handling, parse errors, and flush behavior are pinned in mint-mcp main.rs. The exact four-tool registry and each read-only handler are pinned in mint-mcp lib.rs tools and lib.rs handlers. JSON-RPC method dispatch and error wrapping are pinned in lib.rs JSON-RPC. The read-only boundary is also reflected by the mint-mcp Cargo manifest and the registered HTTP proxy route in broker lib.rs.