Quickstart with MCP

Use this quickstart to connect an OAuth-capable AI client to hosted Shodai MCP, validate a complete agreement JSON artifact, preflight deployment values, and prepare deploy EIP-712 typed data on testnet. You will authenticate through the browser without giving hosted MCP a private key, and you will stop before a live write. 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 uses Shodai’s free testnet environment. Production access is available by request. Request production access.

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.

Connect hosted MCP with browser OAuth

Hosted Shodai MCP uses protected-resource discovery so an OAuth-capable client can locate Shodai’s authorization server and start browser authorization automatically.

Add the hosted server

Add https://shodai.network/mcp as a remote Streamable HTTP MCP server.

Start the connection

Connect to the server and allow your MCP client to open Shodai sign-in in the browser.

Approve access

Confirm the tools are available

Return to your MCP client and confirm that the Shodai Agreements tools are available.

The hosted server is stateless. Each API-calling tool requires environment: "testnet" or environment: "production", and this quickstart uses testnet throughout.

Browser OAuth discovery for https://shodai.network/mcp currently connects to the testnet authorization server. That OAuth connection works only with environment: "testnet"; using it with environment: "production" returns 401. To call production tools through hosted MCP, provide a production API key as Authorization: Bearer cns_pk_... until production MCP OAuth is enabled.

Connect a client that does not support OAuth

Send an API key as Authorization: Bearer cns_pk_.... The key must belong to the same environment passed to each tool, such as a testnet key with environment: "testnet". See Authentication for key creation, storage, production provisioning, and failure details.

Validate and prepare an agreement

Call an authenticated read tool

Call:

list_agreements

with:

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

This confirms the authenticated MCP connection can call the testnet 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

Connect hosted MCP with browser OAuth

Validate and prepare an agreement

Recommended signing harness

Write authority

Run the full lifecycle

​Connect hosted MCP with browser OAuth

​Validate and prepare an agreement

​Recommended signing harness

​Write authority

​Run the full lifecycle

Connect hosted MCP with browser OAuth

Validate and prepare an agreement

Recommended signing harness

Write authority

Run the full lifecycle