MCP Quickstart

Connect Mezcal to Codex, Claude Code, and similar MCP clients without losing the app and API context.

In this guide

Use this surface for Try in app first Current external setup Environment Codex setup Common agent mistakes

Loading documentation content…

MCP quickstart

Use this guide when a tool-calling client needs Mezcal over MCP. Do not start here if a normal service can call HTTP directly or if a human operator is better served by the CLI.

Use this surface for

Codex, Claude Code, and other tool-calling clients
workflows where an agent needs Mezcal tools instead of raw REST requests
reusing the same Mezcal API key surface while keeping rollout access bounded

Try in app first

Before you connect an agent, look at the same explorer surfaces on the current host:

That keeps the agent workflow grounded in the same product behavior that Mezcal users actually see.

Current external setup

Today the cleanest setup is:

install the mezcal CLI using the Agent CLI guide
export the same MEZCAL_* variables used by REST and CLI
let the AI client run mezcal mcp serve --transport remote

Environment

export MEZCAL_BASE_URL="https://<your-mezcal-host>/api"
export MEZCAL_API_KEY="mzk_test_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"

Codex setup

codex mcp add mezcal \
  --env MEZCAL_BASE_URL=$MEZCAL_BASE_URL \
  --env MEZCAL_API_KEY=$MEZCAL_API_KEY \
  --env MEZCAL_CHAIN=$MEZCAL_CHAIN \
  -- mezcal mcp serve --transport remote

Useful starter tools for Mezcal replacement workflows:

status
token_total_supply
token_balance_of
token_transfers

Common agent mistakes

search is identifier-first, not ticker or symbol search, and some responses normalize into canonical padded felt forms.
contract_entrypoints is broader than contract_read; for read, prefer selectors with stateMutability=view and pass required calldata.
address_token_holdings is the wallet-screening surface. Treat it as complete only when exact=true and truncated=false.
On very active wallets, separate latest calls to holdings and token_balance_of can drift numerically if the chain moved between requests. Missing a core-token row on a completed holdings response is the stronger bug signal.

Claude Code setup

claude mcp add --scope project --transport stdio \
  --env MEZCAL_BASE_URL=$MEZCAL_BASE_URL \
  --env 'MEZCAL_API_KEY=${MEZCAL_API_KEY}' \
  --env MEZCAL_CHAIN=$MEZCAL_CHAIN \
  mezcal -- mezcal mcp serve --transport remote

Check that Claude Code sees it:

claude mcp list

Hosted MCP transport

Mezcal also exposes a native HTTP MCP endpoint at:

{baseUrl}/mcp (for hosted external clients, this resolves to /api/mcp)

This is documented here instead of the REST reference because it is a JSON-RPC transport, not the normal explorer HTTP surface.

Current behavior:

POST /mcp accepts one JSON-RPC message per request
inline JSON responses return as application/json
notifications and JSON-RPC responses return 202 Accepted
GET /mcp returns 405 Method Not Allowed

Smoke-test the remote MCP path

MEZCAL_BASE_URL="https://<your-mezcal-host>/api" \
MEZCAL_API_KEY="$MEZCAL_API_KEY" \
./rust-exp/scripts/release-mcp-remote-smoke.sh

This exercises a real JSON-RPC session over stdio:

initialize
notifications/initialized
tools/list
tools/call for __mezcal_init__
tools/call for status
tools/call for block_detail

When not to start with MCP

Use the REST API for direct service integrations.
Use the SDK for typed application code.
Use the CLI when you need explicit commands and local exports.
Stay in the explorer app when the job is visual investigation rather than tool-calling.