> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shodai.network/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart with MCP
> Configure hosted MCP, call authenticated tools, validate an example agreement, and prepare EIP-712 typed data without giving the server a private key.
For the complete documentation index, see [llms.txt](https://docs.shodai.network/llms.txt).
Do not confuse the docs-domain MCP server with the Agreements execution MCP server. Any MCP card or MCP endpoint on `docs.shodai.network` is for documentation search and retrieval only. To author, validate, deploy, or operate agreements, configure the Agreements execution MCP server at `https://shodai.network/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](/sdks/quickstart-with-typescript-sdk). To compare the two first-run paths, start with [Choose an integration surface](/integration-surfaces).
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.
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
Ask your connected client to run `tools/list`, or use MCP Inspector:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
list_agreements
```
with:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"environment": "testnet",
"limit": 25
}
```
This confirms the hosted MCP server can authenticate your key and call the Agreements API.
Run `resources/list`, then read:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
agreements://examples/simple-agreement.json
```
Parse the returned `contents[0].text` value as `agreement` for the remaining tool calls.
Call:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
validate_agreement
```
with:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"environment": "testnet",
"agreement": ""
}
```
Confirm the response includes participant variable keys, input IDs, state IDs, and warnings.
Choose public wallet addresses for the first-flight deployment context. Hosted MCP needs addresses only, not private keys.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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.
Call:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
preflight_deployment
```
with:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"environment": "testnet",
"agreement": "",
"chainId": 59141,
"participants": [
{
"variableKey": "partyAEthAddress",
"walletAddress": "0x1111111111111111111111111111111111111111"
},
{
"variableKey": "partyBEthAddress",
"walletAddress": "0x2222222222222222222222222222222222222222"
}
]
}
```
Review `variables`, `participants`, `observers`, `contributors`, and `warnings` before preparing typed data.
Call:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
prepare_deployment_typed_data
```
with the same `environment`, `agreement`, `chainId`, `signerAddress`, and `participants`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"environment": "testnet",
"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 `@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 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](/sdks/typescript-client). For low-level payload semantics and debugging, see [EIP-712 signing](/reference/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](/examples/end-to-end-workflow). That tutorial shows how the MCP and TypeScript SDK paths converge for live deployment, signed input submission, state reads, and input history.