Skip to main content
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

1

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.
2

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.
3

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.
4

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.
5

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.
6

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.
7

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
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 @cns-labs/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 pathUse it when
Existing wallet or signing serviceYour agent host already exposes an EIP-712 signer.
TypeScript SDK + viemYou need a local testnet signing harness for the typed data returned by MCP.
API PlaygroundYou want browser-based experimentation with a key you control.
Local stdio MCP signerYou 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.