Developers
MCP reference
The same ARK as an MCP server. Stateless Streamable HTTP: every POST is a complete JSON-RPC call and no session id is issued.
The server
https://www.arkz.ai/mcp
The URL takes POST with a JSON-RPC 2.0 body. Send the credential as a bearer credential.
Protocol versions the server accepts: 2025-06-18 2025-03-26 2024-11-05
Set up any MCP client
- Add a remote MCP server in your client.
- Server URL: the URL above.
- Transport: Streamable HTTP.
- Header: Authorization: Bearer <your key>. A client that supports OAuth can sign in instead, through the discovery documents on the Authentication page.
- Reload the client; it calls tools/list and shows the tools your credential may use.
- A source key (ark_src_) cannot run an MCP session: initialize and tools/list answer -32003. A source uses REST, or sends bare tools/call messages for its three tools.
Clients that only speak stdio can run the bridge in the ARKZ repository (mcp/arkz-mcp-server/index.mjs) with node. It reads ARKZ_API_KEY from its environment, forwards to the REST endpoint and offers the three live tools.
{
"command": "node",
"args": [
"/absolute/path/to/mcp/arkz-mcp-server/index.mjs"
],
"env": {
"ARKZ_API_KEY": "<your owner key>"
}
}initialize, tools/list and tools/call
curl -s https://www.arkz.ai/mcp \
-H "Authorization: Bearer $ARKZ_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_ark_profile",
"arguments": {}
}
}Every tool
The input schemas below are rendered from the same definitions the server lists.
ask_arkLive
Ask the connected ARK a question and get a retrieval-augmented answer in the creator’s voice. Billable to the ARK owner.
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
question | string | yes | The question or prompt for the ARK. |
get_ark_profileLive
Get the connected ARK’s public profile: name, tagline, mastery level, primary domain, and how many shareable insights it has.
Input
No parameters.
search_ark_topicsLive
Discover what the ARK knows: its topic coverage over shareable insights (no private/vault content is returned). Optionally filter by a substring.
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
query | string | no | Optional substring to filter topics. |
get_ark_schemaEarly access
The published ARK Record Protocol v0: the record and scope JSON Schemas, the facets and kinds, authorship, trust tiers, privacy and error codes. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
No parameters.
list_ark_recordsEarly access
A page of the connected ARK's records as protocol envelopes, within this credential's privacy ceiling (vault content is never returned). Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
filter | object | no | Optional. Narrows the records (it can never widen what the credential may read). Keys: facets, kinds, domains, topics, authorship, privacy, record_refs, status (lists), trust_min (T0 to T4), since, until (dates), provenance {owner_sources, documents, sessions, integrations, grants, credential_kinds}. Record format: https://www.arkz.ai/protocol/v0/record.schema.json | |
limit | integer | no | minimum 1, maximum 100 | Page size, 1 to 100 (default 50). |
after | string | no | The next_after value of the previous page. |
get_ark_recordEarly access
One record of the connected ARK as a protocol envelope, with its lineage. Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
record | string | yes | The record id (rec_<uuid>) or its ref. |
get_ark_provenanceEarly access
Where the connected ARK's readable records came from, with counts: owner sources, documents, sessions, integrations, grants, credential kinds, trust tiers and authorship. Never a record's text. Needs the read:records scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
No parameters.
propose_ark_recordEarly access
Proposes one record to the connected ARK as a protocol envelope (arp "0", ark, facet, kind, authorship, content, provenance.content_sha256). Nothing is spent and nothing enters the ARK until its owner accepts it; trust_tier and id are assigned by ARKZ and ignored. Answers {proposal_id, status, lane}, {status: "duplicate", duplicate_of}. Needs the write:proposals scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
envelope | object | yes | One ARK Record v0 envelope. provenance.content_sha256 is the lower-case hex SHA-256 of the canonical content and is recomputed by ARKZ. Record format: https://www.arkz.ai/protocol/v0/record.schema.json |
propose_ark_recordsEarly access
Proposes up to 100 records to the connected ARK in one call, one result per envelope in order; one refused item never stops the rest. Nothing is spent until the owner accepts. Needs the write:proposals scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
envelopes | object[] | yes | minItems 1, maxItems 100 | 1 to 100 envelopes. |
get_ark_proposal_statusEarly access
The status of proposals THIS credential wrote (a source key sees its grant's), status only: proposal_id, status (proposed, held, accepted, rejected, expired; not_found for an id that is not yours), created_at, decided_at. Send proposal_ids (1 to 100) or list newest first with since, limit and the previous page's next as after. Never content, a reason or a charge; one ledger row, no quota, free. Needs the write:proposals scope. Record format: https://www.arkz.ai/protocol/v0/record.schema.json. Documentation: https://www.arkz.ai/developers
Input
| Name | Type | Required | Limits | Description |
|---|---|---|---|---|
proposal_ids | string[] | no | minItems 1, maxItems 100, items format uuid | 1 to 100 proposal ids; the answer keeps their order. |
since | string | no | format date-time | Listing only: proposals created at or after this time. |
limit | integer | no | minimum 1, maximum 100 | Listing only: page size, 1 to 100 (default 50). |
after | string | no | maxLength 200 | Listing only: the next value of the previous page. |
Errors over MCP
A tool that ran and failed answers a normal result with isError true and one text item: a live tool's text starts with "Error:"; a protocol tool's text is the JSON body REST would send, {"error": "<code>", "message": "..."}, so parse the JSON for the code. A malformed call answers a JSON-RPC error object.
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "Error: <message>"
}
],
"isError": true
}
}