# MCP quickstart

> Connect ChatGPT and Claude through passwordless OAuth at /mcp/oauth, or configure a direct MCP client at /mcp, then safely operate Agreebase workflows.

Audiences: developers, agents
Kind: guide
Updated: 2026-07-17

This is the shortest reliable path from an MCP client to an Agreebase result. Use it when your client can connect to a streamable HTTP MCP server. For the complete tool contract, see the [MCP reference](/docs/developers/mcp-reference).

Agreebase is an agent-human system. An agent may prepare a record and carry a workflow forward, but the human remains responsible for the exact text, secret inputs, signatures, and consequential confirmations. Agreebase is not a legal service.

## 1. Connect ChatGPT or Claude

Use this endpoint for a hosted custom connector:

```text
https://agreebase.com/mcp/oauth
```

In ChatGPT, add a custom MCP app and enter that URL. In Claude, add a custom remote connector and enter the same URL. The host discovers Agreebase OAuth, registers its connector, and opens the authorization page. Complete:

```text
Connect → enter email → enter OTP → Verify and connect
```

For ChatGPT, open the workspace's app/connector settings, choose to create a custom MCP app, set the server URL to `https://agreebase.com/mcp/oauth`, save, and choose **Connect**. This hosted custom-MCP facility is available only on supported Business, Enterprise, and Edu workspaces.

For Claude, open **Settings → Connectors**, choose **Add custom connector**, set the remote MCP URL to `https://agreebase.com/mcp/oauth`, add it, and choose **Connect**. Claude registers its HTTPS callback dynamically; do not create or paste an Agreebase client secret.

The page identifies the requesting client and exact registered redirect origin, summarizes the permissions, and states that the connection lasts up to 90 days. There is no Agreebase account registration, password, or API key to create or paste. Do not give an API key or OTP to the agent in chat; the host owns the transport ceremony.

The hosted connection grants `create`, `retrieve`, `verify`, `amend`, `cancel`, and `offline_access`. Access tokens last one hour and refresh automatically with rotation until the fixed 90-day consent boundary. Disconnecting revokes the connection. Refresh never expands scopes or extends that boundary.

ChatGPT's custom MCP facility must be available to the user's workspace. Claude must support remote custom connectors. These are hosted MCP connections, not a ChatGPT Action, Custom GPT Action, marketplace app, plugin, or Apps SDK UI.

## 1.5 Connect a direct or raw client

Direct clients use:

```text
https://agreebase.com/mcp
```

This endpoint retains public verification and credentials explicitly configured by the client operator. A raw client uses the streamable HTTP sequence below:

1. `POST /mcp` an `initialize` request with `Content-Type: application/json` and `Accept: application/json, text/event-stream`.
2. Save the `Mcp-Session-Id` response header.
3. Send `notifications/initialized` with that session ID.
4. Send `tools/list` before relying on a tool name, input schema, enum, or annotation.
5. Send `tools/call` requests with the same session ID.

The server may return each JSON-RPC response as an SSE `message` event whose `data` value is the JSON-RPC envelope. A client should accept either an SSE response or an ordinary JSON response and should read the structured result when the server provides `structuredContent`.

An initialization request looks like this:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-agent",
      "version": "1.0.0"
    }
  }
}
```

After initialization, send this notification. Notifications have no `id` and do not require the client to interpret a result:

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}
```

Then discover the current contract:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

The server's negotiated protocol version is authoritative. If a client does not advertise `text/event-stream`, the endpoint may return `406 Not Acceptable`.

## 2. Make the first safe call

Public verification does not require authentication. This call asks whether a record exists and returns a public certificate when no artifact is supplied:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "verify_agreement",
    "arguments": {
      "agr_reference": "AGR-ABCD-EFGH"
    }
  }
}
```

For a real artifact, include the strongest value available. For a notarized file or hash record, `content_hash` is normally the correct field:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "verify_agreement",
    "arguments": {
      "agr_reference": "AGR-ABCD-EFGH",
      "content_hash": "sha256:969e2d23155e65aa91b0bd6ae2688deb2e0c2f6fbf74ebee2721d5f5983c204d"
    }
  }
}
```

Interpret the result using these fields together:

- `record_found` says whether the reference resolved.
- `record_match` says whether the submitted artifact matched the record.
- `verified` is the final verification result.
- `verdict` distinguishes `verified`, `certificate`, `matched_superseded`, `matched_not_sealed`, `no_match`, and `not_found`.
- `current_authority` says whether the matched record is the current authority.
- `match_method` identifies the successful comparison.
- `status` and `sealed_at` describe sealing independently of artifact matching.

Reference-only verification is a certificate lookup. It is not proof that a particular file or text copy matches.

## 2.5 Choose image and card representations

Agreement reads, lists, and verification calls return compact image metadata by default. The metadata includes the [identicon](/docs/concepts/identicons) kind, digest, short hash, dimensions, accessible alt text, and availability; it does not include image bytes or a data URI. Ask for `visual_representation="inline"` when the MCP host can render native image content:

```json
{
  "name": "verify_agreement",
  "arguments": {
    "agr_reference": "AGR-ABCD-EFGH",
    "visual_representation": "inline"
  }
}
```

Use `visual_representation="compatibility_data_uri"` only for a legacy host that explicitly needs an SVG data URI. Inline image bytes are placed in an MCP image content block, not in `structuredContent` or the first text block. Those two redacted payloads are intentionally identical.

Public verification and agreement listings inline document identicons only. After participant authentication, use `get_agreement` for permitted party signature identicons or the signature-execution tools for the current caller's finalized signature identicon.

Share cards are private artifacts. After the existing participant authentication succeeds, call `get_agreement_card` with no representation to receive a short-lived, single-use URL:

```json
{
  "name": "get_agreement_card",
  "arguments": {
    "agr_reference": "AGR-ABCD-EFGH",
    "representation": "url"
  }
}
```

Use `representation="inline"` for native MCP PNG content, or the deliberate `compatibility_base64` mode for an older client. The URL uses the configured public/base URL, expires after the configured short TTL (five minutes by default), and cannot be redeemed twice. Never log or persist the ticket.

## 3. Authentication is transport-level

On `/mcp/oauth`, ChatGPT or Claude completes authentication before MCP initialization. The agent does not call an authentication tool to create the connection and must never request an API key in chat. `get_authentication_status` reports the OAuth principal and all granted scopes. The authentication bootstrap tools remain visible because `/mcp/oauth` and `/mcp` deliberately share the same 27-tool discovery catalogue, but hosted connectors do not need them.

For a direct `/mcp` session, check the current transport or session first:

Check the current transport or session first:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_authentication_status",
    "arguments": {}
  }
}
```

The response reports `authenticated`, `scopes`, `auth_method`, and whether the credential is `session_bound`.

If direct-client retrieval access is needed and no transport credential is configured:

1. Call `request_authentication_otp` with the user's email.
2. Tell the user that Agreebase sent a short-lived six-digit authentication code and wait for the user to provide it.
3. Call `verify_authentication_otp` with the returned `verification_event_id` and the user-provided code.
4. Keep using the same MCP session. A session-bound result grants the `retrieve` scope for up to 600 seconds.
5. Call the tool named by `next_action`, normally `list_agreements` or `get_agreement`.

That direct-client OTP bootstrap is intentionally limited to retrieval. Creating records, executing signatures, and lifecycle changes require a transport credential with the exact returned scope. A transport `Authorization: Bearer` credential may be an Agreebase API key or a short-lived MCP transport token. Never put a long-lived API key in a tool argument or chat message.

An OAuth authentication OTP and every direct-client authentication OTP have purpose `authenticate`. They authorize access only. They can never seed a signature method, satisfy `can_finalize`, create signature evidence, or finalize a record. Every signature still requires the separate record/version-specific ceremony returned by the signature tools.

## 4. Create, sign, and seal a record

Creation tools are consequential. Show the exact final text to the human before calling one, and make publication choices explicit. A minimal agreement call has these required arguments:

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "create_agreement",
    "arguments": {
      "body": "The complete final agreement text, including the obligations and dates the parties approved.",
      "other_party_email": "counterparty@example.com",
      "other_party_name": "Counterparty",
      "on_chain_full_text": false,
      "on_chain_include_verified_parties": false,
      "required_signature_method_count": 1
    }
  }
}
```

A successful creation response contains the AGR reference, an initiator signature state, and usually `next_action` and `human_step`. Follow the exact tool and arguments returned there. Do not infer a signature method from prose.

The signature loop is:

1. Call `start_or_resume_signature_execution` if the returned next action asks for it.
2. Call `start_signature_method` for the selected method.
3. Give the human the exact `human_step.prompt`, proof text, proof title, URL, or challenge instructions returned by Agreebase.
4. Submit only the short-lived user-provided value through `submit_signature_method_input`.
5. Refresh asynchronous methods with `refresh_signature_method` when the next action requests it.
6. Repeat until `signature_execution.can_finalize` is true.
7. Show the exact final text again and obtain affirmative human confirmation.
8. Call `finalize_signature_execution` only after that confirmation.

Email signature OTPs, authentication OTPs, public proof URLs, Telegram challenges, and passkey payloads are different inputs. Never substitute one for another. Other participants may still need to complete their own current version signatures after the initiator finalizes.

## 5. Use previews before consequential lifecycle actions

Amendments, draft updates, participant changes, invitation resends, witness actions, rescissions, cancellations, declines, and counter-proposal resolution are all guarded. The safe sequence is:

1. Call the matching `preview_*` tool.
2. Read the actor, target, current status, agreement version, consequences, notifications, and sealing or blockchain effect.
3. Summarize those consequences to the human and obtain explicit confirmation.
4. Call the matching execute tool with the preview's `confirmation_token`, the same target arguments, and the preview's `agreement_version`.
5. If the token expires or the version changes, call the preview again. Do not retry the old execute call blindly.

The execute tool's `confirmation_token` is short-lived and bound to the principal, scope, record, target, and version that produced the preview.

## 6. Treat every response as a workflow instruction

On a successful response, inspect `next_action` and `human_step` before writing your own next step. On a recoverable failure, inspect `error_code`, `required_scopes`, `retry_after_seconds`, and `retry_action`.

The most useful agent rules are:

- `auth_required`: obtain the required authentication or ask the user to connect a permitted transport credential.
- `missing_scope`: report the exact missing scope; do not guess or request a broader scope silently.
- `confirmation_required`: call the named preview tool.
- `stale_confirmation_token`, `expired`, or `conflict`: refresh the preview or restart the current workflow from the returned retry action.
- `rate_limited`: wait for `retry_after_seconds`; do not loop aggressively.
- `validation_error`: correct the arguments using the live `tools/list` schema.

The complete response and tool catalog are in the [MCP reference](/docs/developers/mcp-reference).