Connect an agent to Tunc Orb

Agents use Tunc Orb through the MCP adapter or the HTTP API. This website manages your account; it never reads or shows what your agents store.

Coming soon: agent access through MCP, A2A and the REST API. This page shows how connecting will work. In Tunc Hub, Orb is built in; read how it works.

The MCP adapter

tunc-orb-mcp gives any MCP client the data_read, data_write and data_delete tools. Add it to your client:

{
  "mcpServers": {
    "tunc-orb": { "command": "tunc-orb-mcp" }
  }
}

On first use it starts a device connection and shows a code such as BCDF-GHJK with a link to https://tuncorb.com/account/agents/connect?code=BCDF-GHJK. Open the link, sign in, check that the code matches and approve. The adapter keeps the connection credential locally; it never belongs in a prompt.

The HTTP API

Start a device connection

curl -s https://core.tunc.ai/api/v1/agent-connections/device \
  -H 'content-type: application/json' \
  -d '{"label":"report-writer on build-server"}'
# → {"device_code":"…","user_code":"BCDF-GHJK",
#    "verification_uri":"https://tuncorb.com/account/agents/connect",
#    "verification_uri_complete":"https://tuncorb.com/account/agents/connect?code=BCDF-GHJK",
#    "interval":5,"expires_in":600}

Approve it

Open verification_uri_complete in a browser, sign in and approve. You can also enter the code at tuncorb.com/account/agents/connect.

Collect the credential

curl -s https://core.tunc.ai/api/v1/agent-connections/device/token \
  -H 'content-type: application/json' \
  -d '{"device_code":"<device_code>"}'
# → {"status":"pending"} until you approve, then once:
# → {"connection_id":"…","credential":"<shown once>","core_url":"…","orb_url":"https://api.tuncorb.com"}

Poll no faster than intervalseconds. The credential is shown once; store it in your system's secret store.

Get a short-lived access token

curl -s -X POST https://core.tunc.ai/api/v1/orb/token \
  -H "authorization: Bearer $TUNC_AGENT_CREDENTIAL" \
  -H 'content-type: application/json' -d '{}'
# → {"access_token":"…","token_type":"Bearer","expires_in":300,"orb_url":"https://api.tuncorb.com",…}

Access tokens last at most five minutes. Request a new one when it expires; revoking the connection stops renewal.

Write, read and delete

Every request is JSON with an operation. Writes and deletes carry a mutation_id you generate once per intended change and reuse on retries, so a retry never applies twice.

curl -s https://api.tuncorb.com/v1/write \
  -H "authorization: Bearer $ORB_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"operation":"create","name":"projects/q4/summary",
       "about":"Weekly summary of the Q4 project",
       "value":{"status":"on track"},
       "mutation_id":"mut_<26 lowercase base32 characters>"}'

curl -s https://api.tuncorb.com/v1/read \
  -H "authorization: Bearer $ORB_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"operation":"get","name":"projects/q4/summary"}'

# List names under a prefix (paged):
curl -s https://api.tuncorb.com/v1/read \
  -H "authorization: Bearer $ORB_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"operation":"list","prefix":"projects/","limit":50}'

curl -s https://api.tuncorb.com/v1/delete \
  -H "authorization: Bearer $ORB_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"operation":"record","name":"projects/q4/summary",
       "if_revision":"rev_…","mutation_id":"mut_…"}'

Omit shelf_id to use your default shelf; every result echoes the shelf it used so retries can pin it.

What the tools do

• data_read: shelves lists shelves you can use; list pages names under a prefix; get reads a record (optionally parts of a JSON value); log reads log entries; search finds text within a prefix; status reports the outcome of an earlier change.
• data_write: create a record with an about line describing it, replace or patch it at a known revision, or append entries to a log.
• data_delete: delete a record, a whole log, or selected log entries, at a known revision.

Every agent connected as you can use every shelf you can access, including records written by your other agents. Disconnecting one agent leaves the others working.

Encryption

Tunc Orb uses managed encryption. Record values are encrypted with a per-shelf data key before they are stored; Tunc's key service protects those keys, and the Tunc Orb service decrypts values to answer your authorized agents. Tunc may process the data to run the service. This is not end-to-end encryption.

What the website shows

Storage used, operation counts, costs, shelf labels and lifecycle, and agent connections. It has no record browser, preview, search, editor or export, and your website sign-in is not an agent credential.