Connect via MCP - Shodai Developer Documentation

The Agreements API ships an open-source Model Context Protocol server, @cns-labs/agreements-mcp-server, hosted at one Streamable HTTP endpoint on the Developer Portal domain. Configure Shodai as a remote MCP server with a bearer API key and the full agreement lifecycle — author, validate, preflight, deploy, submit inputs — becomes callable as MCP tools, with auth, entitlements, and metering enforced by the same gateway that serves /v0 requests.

Configure Shodai as a remote Streamable HTTP MCP server.

URL:
https://developers.shodai.network/mcp

Auth:
Authorization: Bearer $SHODAI_API_KEY

Key shape:
cns_pk_...

Tool environment:
testnet

Use this value as the environment argument on API-calling tools. API keys only work in the environment where they were created.

Hosted API-calling tools require an environment argument: testnet or production. API keys only work in the environment where they were created, so a testnet key must be used with environment: "testnet" and a production key must be used with environment: "production".

Environment	Tool argument
Testnet	`environment: "testnet"`
Production	`environment: "production"`

The server is stateless: every request is authenticated independently, no credential is stored server-side, and only POST is served (no SSE sessions).

Connect a client

Get an API key from the Developer Portal, set it as SHODAI_API_KEY, and translate the setup contract above into your MCP client’s remote Streamable HTTP server configuration. OAuth bearer tokens, JWT bearer tokens, and non-API-key bearer values are not supported. Scope, entitlement, and rate-limit failures surface through tool results with the same 401/402/403/429 semantics described in Authentication and Errors and troubleshooting.

Run locally over stdio

For local development, run the published package over stdio instead of the hosted endpoint:

{
  "mcpServers": {
    "shodai-agreements": {
      "command": "npx",
      "args": ["-y", "@cns-labs/agreements-mcp-server"],
      "env": {
        "AGREEMENTS_API_KEY": "YOUR_API_KEY",
        "AGREEMENTS_API_ENVIRONMENT": "testnet"
      }
    }
  }
}

Stdio mode reads configuration from the process environment:

Variable	Use
`AGREEMENTS_API_KEY`	API key used for tool calls. Required.
`AGREEMENTS_API_ENVIRONMENT`	`testnet` (default) or `production`.
`AGREEMENTS_API_BASE_URL`	Explicit gateway origin override. Wins over the environment.
`AGREEMENTS_SIGNER_PRIVATE_KEY`	Optional local permit signer for write tools (dev/testnet pattern).
`INFURA_PROJECT_ID`	Infura project ID used to derive RPC URLs for the built-in Linea, Sepolia, and Base agreement chains.
`AGREEMENTS_RPC_URL`, `AGREEMENTS_RPC_URL_<chainId>`	Optional RPC overrides used when preparing or signing permits.

Tools

Most tools call the public /v0 API through the TypeScript client and carry MCP behavior annotations (readOnlyHint, destructiveHint) so clients can require confirmation before on-chain writes. A few tools perform more than one operation to keep signing and deployment safe. On the hosted endpoint, every API-calling tool below requires environment: "testnet" | "production". Local stdio mode uses the fixed environment from AGREEMENTS_API_ENVIRONMENT instead.

Tool	Wraps	Scope
`list_agreements`	`GET /v0/agreements`	`agreements.read`
`get_agreement`	`GET /v0/agreements/{id}`	`agreements.read`
`get_agreement_document`	`GET /v0/agreements/documents/{documentId}`	`agreements.read`
`get_agreement_state`	`GET /v0/agreements/{id}/state`	`agreements.read`
`get_input_history`	`GET /v0/agreements/{id}/inputs`	`agreements.read`
`validate_agreement`	`POST /v0/agreements/validate-template`	`agreements.write`
`preflight_deployment`	`POST /v0/agreements/validate`	`agreements.write`
`deploy_agreement`	`POST /v0/agreements/validate`, then `POST /v0/agreements/deploy-with-permit`	`agreements.write`
`submit_input`	`POST /v0/agreements/{id}/input`	`agreements.write`
`prepare_deployment_typed_data`	`POST /v0/agreements/validate`, then local EIP-712 payload construction with a chain nonce read	`agreements.write`
`prepare_input_typed_data`	`GET /v0/agreements/{id}`, then local EIP-712 payload construction with a chain nonce read	`agreements.write`

The server also exposes MCP resources (the simple and complex example agreements, the authoring guide, and the documentation index) and an author_agreement prompt that turns a business description into agreement JSON. Use resources/list to discover the available resources.

Resource	URI
`simple-example-agreement`	`agreements://examples/simple-agreement.json`
`complex-example-agreement`	`agreements://examples/complex-agreement.json`
`authoring-guide`	`agreements://docs/author-agreement-json.md`
`docs-index`	`agreements://docs/index.md`

Signing custody modes

Deploying agreements and submitting inputs require EIP-712 permits, signed by a wallet the agreement recognizes. The write tools support three custody modes; pick the one that matches who holds the key. For payload details, see EIP-712 signing.

1. Pass a pre-signed permit

If the agent or its host application already holds a wallet (for example through wallet tooling or an agent-generated key), sign the permit outside the MCP server and pass signer, deadline, signatureV, signatureR, and signatureS directly to deploy_agreement or submit_input. The MCP server never sees the private key.

2. Prepare typed data, sign externally

Call prepare_deployment_typed_data or prepare_input_typed_data to get the exact EIP-712 payload (domain, types, message, deadline) the gateway expects. Sign it with any EIP-712-capable signer — a human wallet, a signing service, or viem — then pass the resulting signature to the matching write tool. For deployments, pass the returned normalizedInitValues, normalizedParticipants, and normalizedObservers back to deploy_agreement with the signature so participant wallet mappings match the signed payload. This is the recommended mode for assistant-style agents where a human or external system controls the key.

3. Local environment signer (stdio only)

In stdio mode, set AGREEMENTS_SIGNER_PRIVATE_KEY and the write tools sign permits locally using the SDK’s permit helpers. The hosted endpoint never signs with server-side keys. Use this for development and testnet automation only; do not put production keys in environment variables.

Minimal hosted lifecycle

For a hosted MCP flow with external signing:

Read the simple-example-agreement resource.
Call validate_agreement with the environment matching your API key.
Call preflight_deployment with the same environment.
Call prepare_deployment_typed_data with the same environment, agreement, chainId, signerAddress, and any intended initValues, participants, observers, and docUri.
Sign the returned typed data externally.
Call deploy_agreement with the same environment, agreement, displayName, chainId, the same docUri, normalizedInitValues as initValues, normalizedParticipants as participants, normalizedObservers as observers, and the permit fields.
Read state with get_agreement_state using the same environment.
Call prepare_input_typed_data with the same environment, agreementId, inputId, values, and signerAddress.
Sign the returned typed data externally.
Call submit_input with the same environment, then reread get_agreement_state and get_input_history.

Hosted MCP receives signed permit fields only, never private keys. Private-key environment signing is for local stdio development and testnet automation only.

Verify the connection

Ask your connected agent to call list_agreements, or run the MCP Inspector against the endpoint:

npx -y @modelcontextprotocol/inspector@latest --cli https://developers.shodai.network/mcp \
  --transport http --method tools/list --header "Authorization: Bearer $SHODAI_API_KEY"

Pin @latest: older Inspector versions cached by npx do not support --transport and --header for URL targets and fail with Arguments cannot be passed to a URL-based MCP server. For a raw Streamable HTTP check:

MCP_URL=https://developers.shodai.network/mcp

curl -sS "$MCP_URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $SHODAI_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

If a client’s bearer-header path is broken, Shodai also accepts the same key as X-API-Key. A successful check returns the tools listed above (use --method resources/list to see the example-agreement resources). From there, a typical first run is: read the simple example resource, validate_agreement, preflight_deployment, then deploy on testnet using one of the custody modes.

​Connect a client

​Run locally over stdio

​Tools

​Signing custody modes

​1. Pass a pre-signed permit

​2. Prepare typed data, sign externally

​3. Local environment signer (stdio only)

​Minimal hosted lifecycle

​Verify the connection