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.

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.

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:

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:

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:

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:

{
  "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:

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

Then discover the current contract:

{
  "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:

{
  "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:

{
  "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 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:

{
  "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:

{
  "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:

{
  "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:

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

Discard changes?

Are you sure? Your draft and any progress will be lost.