Integrate Carver’s AI-Agent Obligations MCP Server

Endpoint and prerequisites

The production endpoint is https://eli.carveragents.ai/api/v1/mcp. Agent Legal API supplies the documentation and web entry point; the MCP service is hosted on Carver ELI. The public discovery document identifies this resource and its authorization server.

Use an approved Carver workspace membership or a workspace you can create during sign-in. The service scopes tools and records to your selected organization. An API key belongs to its owner’s organization; it does not grant cross-organization access. Never place a key in a URL, public repository, or client-side bundle.

Connect with OAuth

For an MCP client supporting Carver’s OAuth flow:

claude mcp add --transport http carver https://eli.carveragents.ai/api/v1/mcp
claude mcp login carver

Complete browser sign-in and choose the workspace. In Claude Code, use /mcp to inspect the connection. Re-authenticate when you need to change workspaces. Client commands follow Claude Code’s MCP documentation; other clients have their own configuration interfaces.

Use an API key for direct requests

For a server-side integration with an issued Carver API key, send X-API-Key on each request. The variable below must contain your own key. This discovery request does not create an assessment:

curl --fail-with-body https://eli.carveragents.ai/api/v1/mcp \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $CARVER_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The transport uses JSON-RPC 2.0 over HTTP POST. tools/list describes the tools and schemas available to this caller. Tool availability and returned result depth can depend on the plan. HTTP GET is not the tool transport; the service does not issue an MCP session ID or provide a server-to-client SSE stream.

Read request and response

To list the current workspace’s agents, send:

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_ai_agents","arguments":{}}}

For an empty workspace, a successful response has this shape. This is an illustrative example, not a captured customer response; whitespace in the text representation may differ.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{"type": "text", "text": "{\"agents\": [], \"total\": 0}"}],
    "structuredContent": {"agents": [], "total": 0},
    "isError": false
  }
}

Use structuredContent for programmatic consumption and check isError before reading it. A missing or inaccessible agent produces a tool error rather than this successful empty-list response. An empty result is scoped to the authenticated workspace; it says nothing about other organizations.

Complete tool sequence

Step	Tool	What to retain or check
1	compliance_status	Organization, tier, available quota, and whether another agent can be added
2	draft_agent_profile	Returned twin, next question, needed, and can_confirm
3	draft_agent_profile again	Pass the returned twin back unchanged with the requested answer until confirmation is possible
4	create_agent_profile	Save the completed twin with a name; retain the returned id
5	get_ai_agent	Poll with that ID; inspect state, mapping_status, and coverage
6	list_agent_acts	Use returned act IDs instead of guessing identifiers
7	list_act_obligations	Read pages, inspect decisions and citations, then request full text when needed

Drafting does not save the profile. Saving does: create_agent_profile queues an assessment and consumes applicable quota. Confirm with the person before creating records or recording compliance decisions. Do not automatically repeat a create call after a transport timeout: no idempotency guarantee is documented here. Inspect list_ai_agents before deciding whether another create is necessary.

Start drafting

The description is illustrative. Replace it with your own workflow, deployment locations, data use, decision authority, and human review arrangements.

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"draft_agent_profile","arguments":{"description":"A support assistant answers UK customers, reads account details, drafts replies for human approval, and cannot issue refunds."}}}

The successful result is wrapped in JSON-RPC result. Its structuredContent contains the tool payload; content contains a text representation. For the draft tool, consume the actual returned twin, question, needed, can_confirm, and summary; their contents depend on the workflow. Do not synthesize missing twin fields.

Return an answer and save

On later draft calls, supply twin from the previous result and answer as {"question_id":"<returned question ID>","values":["<selected value>"]}. Values are always a list; use the choices and shape requested by the returned question.

Once can_confirm is true, call create_agent_profile with name and the completed twin. An incomplete profile is refused. The returned note says it is queued; that is not a completed legal assessment.

Polling and result interpretation

Call get_ai_agent with {"agent_id":"<returned agent ID>"}. IDs in angle brackets are placeholders, not literal valid IDs.

Returned state	Client behavior
gtm_pending	A quick brief is being prepared; mapping is not complete
gtm_failed	Quick-brief preparation failed; surface the state for support rather than claiming success
needs_answers	The profile is incomplete; obtain the missing facts
waiting	Queued for assessment
assessing	Assessment is in progress
ready	Mapping completed with the recorded coverage marked complete
partial	Mapping completed but the recorded coverage has gaps; disclose them

A suggested client policy is bounded exponential backoff, a visible timeout, and manual retry or support escalation. That is integration guidance, not a server-side polling interval or completion SLA. Completion times and corpus coverage are not guaranteed. ready describes processing and recorded coverage; it is not legal clearance or proof that every relevant law was considered.

Pagination and full text

After obtaining an act ID, a request may look like:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_act_obligations","arguments":{"agent_id":"<returned agent ID>","act_id":"<returned act ID>","limit":25,"offset":0,"full_text":false}}}

list_act_obligations defaults to 25 results, caps a page at 100, and reports total, offset, returned, and has_more. Increment the offset by returned until has_more is false. When a plan restricts scope, plan_total can disclose the untrimmed count. full_text: true returns longer provision and enforcement detail; request it selectively to control context size.

Errors and limits

Signal	Meaning and handling
HTTP 401/403	Authentication or workspace authorization needs attention; do not treat this as an empty assessment
JSON-RPC error	Envelope, method, argument, or authorization error; inspect code and message
HTTP 200 with result.isError: true	The tool could not complete its business operation; inspect its text message
-32700, -32600, -32601, -32602	Invalid JSON, invalid request, unknown method, or invalid parameters respectively
-32000, -32603	Authorization/context error or internal error respectively
Plan refusal, trimmed results, or is_locked	Explain the restriction; do not imply complete access
Network failure or gateway error	Retain request context and use bounded retry for reads; verify before repeating writes

No universal requests-per-minute allowance or latency guarantee is asserted here. Use compliance_status and the caller’s current tools/list rather than hard-coding plan entitlements. Obtain confirmation before using write tools such as answer_obligation, answer_act, assign_gap_owner, or publish_trust_page.

Preserve uncertainty in downstream output

Keep the source citation, applicability condition, missing fact, and recorded decision separate. An unresolved applicability question is not a passed check. Read methodology and coverage before using the results in a release process.