Tutorial · about 10 minutes

Build your first context space.

Connect an agent, create a space, store some context, grant access, ask a focused question, and read the receipt. Every call below is a plain HTTP request you can paste into a terminal.

You need: a Priostack key Tools: curl Protocol: MCP over HTTP

Before you start

The Agent Context Network speaks MCP, the Model Context Protocol, over JSON-RPC. Any MCP client can drive it, but for this walkthrough we use curl so every step is transparent. You will call one endpoint, POST /rpc, and each call names a tool and its arguments.

Set your endpoint and key once so the snippets below just work:

shell

# your account endpoint and key (from the Priostack dashboard)
export ACN="https://api.priostack.com/acn/rpc"
export ACN_KEY="psk_live_your_key_here"

Every request is a JSON-RPC tools/call. The server resolves who you are, what you may reach, and your price from your key. You never declare your own permissions in a request.

Connect

Open a session. The response tells you the identity the server resolved for your key and hands back a sessionId you pass to later calls.

request

curl -s "$ACN" -H "authorization: Bearer $ACN_KEY" -d '{
  "jsonrpc":"2.0","id":1,"method":"tools/call",
  "params":{"name":"noetic.connect","arguments":{"maxResponseTokens":512}}
}'

response

{
  "ok": true,
  "data": {
    "sessionId": "sess-41",
    "resolvedAccount": "acct-1",
    "grantedContextRights": ["read", "write"]
  }
}

Create a space

A space is a partition of your memory with its own contents, permissions, and price. Create one for a focused body of knowledge. Here, notes your support agents should share.

request

curl -s "$ACN" -H "authorization: Bearer $ACN_KEY" -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"noetic.create_space","arguments":{
    "sessionId":"sess-41",
    "displayName":"support-notes",
    "defaultRights":["read","quote","fact_use"]
  }}
}'

response

{
  "ok": true,
  "data": {
    "spaceId": "space-1",
    "tierSpaceUsage": { "used": 1, "cap": 5 }
  }
}

The defaultRights are the ceiling for this space. Anything you grant later can narrow them, never widen them.

Store context

Put real context into the space with noetic.store. Each object carries a type that records what kind of thing it is. Use observation or declaration for things that are true and recorded.

request

curl -s "$ACN" -H "authorization: Bearer $ACN_KEY" -d '{
  "jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{"name":"noetic.store","arguments":{
    "sessionId":"sess-41","space":"space-1",
    "objects":[
      {"content":"Refunds over 30 days require a manager approval code.","type":"declaration"},
      {"content":"Customer ACME reported slow exports on the EU region.","type":"observation"},
      {"content":"The self-serve plan does not include phone support.","type":"declaration"}
    ]
  }}
}'

response

{
  "ok": true,
  "data": { "objectRefs": [
    { "objectRef": "obj-2", "kind": "declaration" },
    { "objectRef": "obj-3", "kind": "observation" },
    { "objectRef": "obj-4", "kind": "declaration" }
  ] }
}

Facts, not guesses. store is for context that is true and recorded. An agent's own hypothesis goes in through a separate path and is always marked as a hypothesis, so a reader can tell the two apart.

Grant an agent

Give an agent access to the space. You choose what it may do with what it reads and how long anything may persist. Request a right the space does not offer and it is quietly narrowed away, never granted.

request

curl -s "$ACN" -H "authorization: Bearer $ACN_KEY" -d '{
  "jsonrpc":"2.0","id":4,"method":"tools/call",
  "params":{"name":"noetic.grant","arguments":{
    "sessionId":"sess-41",
    "subjectPrincipal":"support-bot",
    "resource":"space-1",
    "rights":["read","quote"],
    "persistenceMode":"private_memory"
  }}
}'

response

{
  "ok": true,
  "data": {
    "capabilityRef": "cap-7",
    "effectiveRights": ["read", "quote"],
    "persistence": "private_memory"
  }
}

Keep cap-7. Revoking it later with noetic.revoke ends the agent's access from that point on, and never rewrites the receipts of reads it already made.

Ask a question

Now the payoff. Your agent connects with its own key and asks a focused question. It gets back a small, relevant answer, not the whole space, and the envelope carries a receipt id for the read.

request

# as the support-bot agent (its own key resolves to sess-46)
curl -s "$ACN" -H "authorization: Bearer $BOT_KEY" -d '{
  "jsonrpc":"2.0","id":5,"method":"tools/call",
  "params":{"name":"noetic.query","arguments":{
    "sessionId":"sess-46",
    "text":"What is the refund policy past 30 days?"
  }}
}'

response

{
  "ok": true,
  "data": {
    "answer": "Refunds past 30 days need a manager approval code.",
    "grounded": true,
    "sources": ["obj-2"]
  },
  "receipt": "rcpt-9"
}

The answer is grounded: it came from stored context (obj-2), not from the model's imagination. Ask something the space does not contain and it tells you it does not know, instead of guessing.

Read the receipt

Fetch the receipt for that read. Notice the two numbers that matter: processedTokens, the context examined to answer, and returnedTokens, the tiny answer that came back. You are billed on the first, never the second.

request

curl -s "$ACN" -H "authorization: Bearer $BOT_KEY" -d '{
  "jsonrpc":"2.0","id":6,"method":"tools/call",
  "params":{"name":"noetic.receipt","arguments":{
    "sessionId":"sess-46","receiptId":"rcpt-9"
  }}
}'

response

{
  "ok": true,
  "data": {
    "consumer": "support-bot",
    "space": "space-1",
    "queryCount": 1,
    "processedTokens": 244,
    "returnedTokens": 11,
    "priceMinorUnits": 200,
    "currency": "EUR"
  }
}

Two hundred and forty four tokens were processed to return eleven. The store could hold a million items and a focused answer like this stays about the same size. That is the whole point.

Check your metrics

Finally, see the whole account at a glance with noetic.metrics. As the owner you get caps and headroom, resident context size, query use against your allowance, cost, and per space counters.

request

curl -s "$ACN" -H "authorization: Bearer $ACN_KEY" -d '{
  "jsonrpc":"2.0","id":7,"method":"tools/call",
  "params":{"name":"noetic.metrics","arguments":{"sessionId":"sess-41"}}
}'

response

{
  "ok": true,
  "data": {
    "scope": "owner",
    "account": {
      "tier": "Growth",
      "objectsUsed": 3, "objectHeadroom": 499997,
      "queriesUsed": 1, "queriesRemaining": 499999,
      "costMinorUnits": 200, "currency": "EUR"
    },
    "spaces": [ { "id": "space-1", "queries": 1, "hasPricing": true } ]
  }
}

Prefer a dashboard to raw JSON? Everything above, spaces, grants, usage, receipts and live metrics, is on one screen. Operators can also scrape a /metrics endpoint in Prometheus format.

You are done

Manage it all from the dashboard

You just created a space, filled it, granted an agent, ran a grounded query, and read the bill. The dashboard puts every one of those controls in one place. The deep dive explains why it works the way it does.

Back to overview Read the deep dive