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

> Connect hosted MCP at https://shodai.network/mcp with browser OAuth, validate an agreement, and prepare testnet deployment typed data.

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 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](/sdks/quickstart-with-typescript-sdk). To compare the two first-run paths, start with [Choose an integration surface](/integration-surfaces).

<Info>
  This quickstart uses Shodai's free testnet environment. Production access is available by request. [Request production access](https://developers.shodai.network/support).
</Info>

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

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

<Steps>
  <Step title="Add the hosted server">
    Add `https://shodai.network/mcp` as a remote Streamable HTTP MCP server.
  </Step>

  <Step title="Start the connection">
    Connect to the server and allow your MCP client to open Shodai sign-in in the browser.
  </Step>

  <Step title="Approve access">
    Sign in, review the permissions requested by the client, and approve the connection.
  </Step>

  <Step title="Confirm the tools are available">
    Return to your MCP client and confirm that the Shodai Agreements tools are available.
  </Step>
</Steps>

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

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

<Accordion title="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](/authentication) for key creation, storage, production provisioning, and failure details.
</Accordion>

## Validate and prepare an agreement

<Steps>
  <Step title="Call an authenticated read tool">
    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 authenticated MCP connection can call the testnet Agreements API.
  </Step>

  <Step title="Read the simple example resource">
    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.
  </Step>

  <Step title="Validate the agreement">
    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": "<parsed simple-example-agreement>"
    }
    ```

    Confirm the response includes participant variable keys, input IDs, state IDs, and warnings.
  </Step>

  <Step title="Prepare public deployment values">
    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.
  </Step>

  <Step title="Preflight deployment">
    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": "<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.
  </Step>

  <Step title="Prepare deploy 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": "<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`
  </Step>
</Steps>

## Recommended signing harness

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

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.