Quickstart with MCP

Use this quickstart when an AI agent or MCP-capable client will operate Shodai Agreements through tools. You will connect hosted MCP, call authenticated tools, validate a complete agreement JSON artifact, preflight deployment values, and prepare deploy EIP-712 typed data without giving hosted MCP a private key. For a TypeScript app or service, use Quickstart with TypeScript SDK. To compare the two first-run paths, start with Choose an integration surface.

This quickstart stops after prepare_deployment_typed_data. The returned typed data proves that hosted MCP can assemble the exact deploy authorization payload, including chain nonce/context, without performing a live write.

Configure hosted MCP

Configure Shodai as a remote Streamable HTTP MCP server: docs.shodai.network may expose a separate docs/search MCP surface for retrieving documentation. That server does not execute Agreements API workflows. Use https://shodai.network/mcp for Agreements execution tools.

URL:
https://shodai.network/mcp

Auth:
Authorization: Bearer $SHODAI_API_KEY

Key shape:
cns_pk_...

Tool environment:
testnet

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". The hosted server is stateless: every request is authenticated independently, no credential is stored server-side, and only POST is served.

Verify tool access

List MCP tools

Ask your connected client to run tools/list, or use MCP Inspector:

npx -y @modelcontextprotocol/inspector@latest --cli https://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.

Call an authenticated read tool

Call:

list_agreements

with:

{
  "environment": "testnet",
  "limit": 25
}

This confirms the hosted MCP server can authenticate your key and call the Agreements API.

Read the simple example resource

Run resources/list, then read:

agreements://examples/simple-agreement.json

Parse the returned contents[0].text value as agreement for the remaining tool calls.

Validate the agreement

Call:

validate_agreement

with:

{
  "environment": "testnet",
  "agreement": "<parsed simple-example-agreement>"
}

Confirm the response includes participant variable keys, input IDs, state IDs, and warnings.

Prepare public deployment values

Choose public wallet addresses for the first-flight deployment context. Hosted MCP needs addresses only, not private keys.

{
  "chainId": 59141,
  "signerAddress": "0x1111111111111111111111111111111111111111",
  "participants": [
    {
      "variableKey": "partyAEthAddress",
      "walletAddress": "0x1111111111111111111111111111111111111111"
    },
    {
      "variableKey": "partyBEthAddress",
      "walletAddress": "0x2222222222222222222222222222222222222222"
    }
  ]
}

Use real public addresses from your signing setup for an actual run. The first address is the deploy signer for this first-flight check.

Preflight deployment

Call:

preflight_deployment

with:

{
  "environment": "testnet",
  "agreement": "<parsed simple-example-agreement>",
  "chainId": 59141,
  "participants": [
    {
      "variableKey": "partyAEthAddress",
      "walletAddress": "0x1111111111111111111111111111111111111111"
    },
    {
      "variableKey": "partyBEthAddress",
      "walletAddress": "0x2222222222222222222222222222222222222222"
    }
  ]
}

Review variables, participants, observers, contributors, and warnings before preparing typed data.

Prepare deploy typed data

Call:

prepare_deployment_typed_data

with the same environment, agreement, chainId, signerAddress, and participants:

{
  "environment": "testnet",
  "agreement": "<parsed simple-example-agreement>",
  "chainId": 59141,
  "signerAddress": "0x1111111111111111111111111111111111111111",
  "participants": [
    {
      "variableKey": "partyAEthAddress",
      "walletAddress": "0x1111111111111111111111111111111111111111"
    },
    {
      "variableKey": "partyBEthAddress",
      "walletAddress": "0x2222222222222222222222222222222222222222"
    }
  ]
}

Confirm the response includes:

typedData
signerAddress
chainId
deadline
docUri
documentId
normalizedInitValues
normalizedParticipants
normalizedObservers
preflightWarnings
nextStep
playgroundUrl

Recommended signing harness

Hosted MCP prepares the exact EIP-712 typed data, but signing remains external. If your MCP client or agent host does not already have a wallet, signing service, or eth_signTypedData_v4 flow, install @shodai-network/agreements-api-client and viem locally and use the TypeScript SDK as the happy-path testnet signing harness.

The signing harness is optional because hosted MCP does not require one specific custody model. Use one of these signing paths:

Signing path	Use it when
Existing wallet or signing service	Your agent host already exposes an EIP-712 signer.
TypeScript SDK + `viem`	You need a local testnet signing harness for the typed data returned by MCP.
API Playground	You want browser-based experimentation with a key you control.
Local stdio MCP signer	You are doing development/testnet automation with `AGREEMENTS_SIGNER_PRIVATE_KEY`; do not use this for production keys.

For SDK signing details, see TypeScript client reference. For low-level payload semantics and debugging, see EIP-712 signing.

Write authority

Only deploy_agreement and submit_input are side-effecting tools; submit_input may advance lifecycle state. validate_agreement, preflight_deployment, prepare_deployment_typed_data, and prepare_input_typed_data are non-destructive preparation steps. Scope is not the same as side effect: some non-destructive tools require agreements.write because they validate deployment context or prepare write authorization. Hosted MCP receives signed permit fields only. It never receives private keys. AGREEMENTS_SIGNER_PRIVATE_KEY is local stdio-only and for development/testnet automation.

Run the full lifecycle

After this first flight works, continue to Run an end-to-end agreement workflow. That tutorial shows how the MCP and TypeScript SDK paths converge for live deployment, signed input submission, state reads, and input history.

Start

Workflow

Webhooks

Architecture

Examples

Reference

Configure hosted MCP

Verify tool access

Recommended signing harness

Write authority

Run the full lifecycle

​Configure hosted MCP

​Verify tool access

​Recommended signing harness

​Write authority

​Run the full lifecycle

Configure hosted MCP

Verify tool access

Recommended signing harness

Write authority

Run the full lifecycle