Connecting Your Agents

Your colleagues are the players in Nuggetz. Claude Code, Codex, Cursor, and similar products are the agents they bring to help execute the Nuggets they own.

Agents can help with two workflow stages. For an Assisted nugget, do not claim it: run it once, report the result, and Nuggetz always sends it to the owner's Review Inbox. For an Autonomous nugget, claim the work first and then report it; its trigger and run lease are managed by Nuggetz. The agent API calls Autonomous work loops.

The everyday experience is intentionally small:

1. Open a Nugget you own and choose Run with….
2. Pick the agent you already use.
3. Continue in that agent. It works against the shared finish line and reports back to the workflow.

The person remains the owner throughout. The agent is an executor, and every teammate can see the result, review, and learning that returns.

This guide explains the one-time connection behind that interaction, plus how agents discover and claim work, propose upgrades, and route uncertain results to a person.

If you're new to nuggets and stages, read Workflows & nuggets first.

Recommended first-time flow

Open an Assisted or Autonomous Nugget and choose Run with….

1. Choose Codex or Claude Code under your personal connections.
2. Copy and run the one-line setup command. Your browser opens Nuggetz sign-in, where you choose the team and approve access. There is no Nuggetz API key to copy.
3. Back in the Nugget, choose Continue with…. Nuggetz copies the owner, finish line, and reporting instructions.
4. Paste that work pack into your agent. Its report returns to this Nugget's history and, when a person must decide, to the Inbox.

The OAuth connection is saved by your local agent, so you do the setup once and reuse it for later Nuggets.

If work must run on a schedule or while no teammate is present, add an always-on team agent from Agents. That separate path uses a one-time setup code so the service has its own revocable identity.

Always-on agents

Use Agents at /team/{teamId}/network/agents only for scheduled, repeat, or unattended work. Personal Codex and Claude Code connections do not appear in this list because their actions are authorized and attributed to the signed-in teammate.

Create a setup code and paste it into the agent. The agent registers its identity and gets its own key back:

curl -X POST https://app.nuggetz.ai/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "connect_code": "ngc_your_connect_code",
    "name": "ContentBot",
    "platform": "claude-code"
  }'

The response includes an api_key (shown once, store it securely). Codes created in the app register one agent identity, expire after 24 hours, and can be revoked, so they are safe to paste into that agent's setup.

Lost key? Ask an admin to reconnect the agent

Keys are stored hash-only and shown once. For security, a shared setup code can only register a new agent identity and can never rotate an existing key. If a key is lost, a team admin can remove and reconnect that agent from Agents, then securely deliver the new key.

MCP-only bootstrap

An MCP-only client doesn't need the REST call at all. Connect the MCP endpoint with the setup code itself as the Bearer token:

claude mcp add --transport http nuggetz https://app.nuggetz.ai/api/v1/mcp \
  --header "Authorization: Bearer ngc_your_setup_code"

In this mode the server exposes a single register_agent tool (name, optional platform, description, rotate). Call it, store the returned api_key, then reconnect with Bearer ngt_... for the full toolset.

Manual key fallback

If the agent cannot call the registration endpoint itself, expand Can't use a setup code?. Nuggetz creates its agent identity and shows an MCP command or config containing the key. The key is shown once, inside the setup command/config, so copy it right away. If you lose it, revoke the identity and create a new one.

Running a Nugget with your agent

Open an Assisted or Autonomous Nugget and choose Run with…. Select the agent you want, then continue. Nuggetz copies a plain-language work pack that tells the agent what the Nugget is, who owns it, its definition of done (the stop condition), and how to fetch, run, and report the assignment.

Paste that pack into your agent. If its MCP connection is already set up, it should use Nuggetz tools directly and should not ask you for another token.

Option A: MCP (recommended)

Nuggetz runs a Model Context Protocol server, so MCP-aware agents can talk to it natively. This is the smoothest way to connect: the agent gets five tools it can call directly, no HTTP wiring needed.

The endpoint is https://app.nuggetz.ai/api/v1/mcp. Personal connections use OAuth; always-on agents use their own Bearer key.

Codex — personal OAuth

codex mcp add nuggetz --url https://app.nuggetz.ai/api/v1/mcp \
  && codex mcp login nuggetz

Claude Code — personal OAuth

claude mcp add --transport http nuggetz --scope user https://app.nuggetz.ai/api/v1/mcp \
  && claude mcp login nuggetz

Both commands open Nuggetz sign-in and store the resulting OAuth connection in the local client. The connection acts as you on the team you approve.

Always-on agents, Cursor, and other MCP clients

Add Nuggetz to your client's MCP config:

{
  "mcpServers": {
    "nuggetz": {
      "url": "https://app.nuggetz.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ngt_your_key_here"
      }
    }
  }
}

Remote connectors (Claude, ChatGPT) — no key needed

Claude and ChatGPT custom connectors can't set custom headers, so they use OAuth instead. Add https://app.nuggetz.ai/api/v1/mcp as a remote MCP server / custom connector and leave the credential fields empty: the client discovers the Nuggetz OAuth server automatically, sends you through sign-in, shows the requested access, and asks you to approve a team explicitly.

Two things are different in this mode:

• The connector acts as you, on the team you picked — claims, runs, and proposals show under your name instead of a registered agent's.
• There's nothing to register or rotate. The OAuth grant is limited to the MCP server and the permissions shown on the approval screen. Removing you from the selected team invalidates the grant immediately.

The five tools

Once connected, the agent has these tools:

The tools map onto the same actions as the HTTP API below, so everything in the rest of this guide (corrections, the review loop, proposals) works the same whether you connect over MCP or plain HTTP.

Option B: plain HTTP

If your agent doesn't speak MCP, use the REST API directly. Assisted and Autonomous nuggets use the assignment and report endpoints below with Bearer auth. Skip the claim endpoint for Assisted work; claim Autonomous work before starting it.

Fetch the assignment

The agent asks what it needs to do:

curl https://app.nuggetz.ai/api/v1/loops/NUGGET_ID \
  -H "Authorization: Bearer ngt_your_key_here"

The response is the assignment payload: the nugget's goal, its definition of done, any corrections the team has attached (more on those below), the briefing context (knowledge nuggets the owner linked to this workflow step, with their insights and decisions), the last few runs (so the agent knows what happened last time), and the available exits the next workflow step understands. The agent uses this to do the work.

Report the run

When the agent finishes a run, or gets stuck, it reports back:

curl -X POST https://app.nuggetz.ai/api/v1/loops/NUGGET_ID/update \
  -H "Authorization: Bearer ngt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "result": "Draft written and saved to the content doc.",
    "needs_review": false,
    "confidence": 0.9,
    "links_or_artifacts": ["https://docs.example.com/draft-42"],
    "run_metadata": { "runner": "ContentBot", "model": "claude-fable-5", "cost_cents": 12 }
  }'

The fields:

Assisted reports always appear in the Inbox for a person to resolve. Live run state appears directly on the workflow and in the Nugget's history, next to the instructions it affected.

Discover, claim, and propose

For Autonomous work, agents do not have to be pointed at a specific nugget. They can browse the team's loops, claim the work they want, and suggest improvements as they go. Assisted work starts only from the instructions a person copies to an agent.

Discover loops

List the team's loops:

curl https://app.nuggetz.ai/api/v1/loops \
  -H "Authorization: Bearer ngt_your_key_here"

Add ?unclaimed=true to see only the loops no agent has picked up yet:

curl "https://app.nuggetz.ai/api/v1/loops?unclaimed=true" \
  -H "Authorization: Bearer ngt_your_key_here"

Claim a loop

Claiming a loop sets the agent as the executor and marks the loop running, so two agents don't work the same nugget. Claims are atomic: if two agents race, exactly one wins and the other gets a 409.

curl -X POST https://app.nuggetz.ai/api/v1/loops/NUGGET_ID/claim \
  -H "Authorization: Bearer ngt_your_key_here"

Claiming also starts a run lease (lease_minutes in the response, set per nugget by the owner). If the agent doesn't report within the lease, Nuggetz flags the loop stuck, notifies the owner, releases the executor, and reopens the wake so another agent can pick the work up. Crashed agents don't silently hold loops.

Verified runs: the maker/checker split

Owners can mark a nugget requires verification. On those loops, a completed run doesn't chain the workflow's next step immediately — Nuggetz opens a verify wake instead, asking a different agent to check the run against the definition of done.

A verify wake looks like any other wake, with reason: "verify" and the run to check in its payload. To verify, fetch the run's result from the wake payload, check it against the DoD, and report with verifies_run_id:

curl -X POST https://app.nuggetz.ai/api/v1/loops/NUGGET_ID/update \
  -H "Authorization: Bearer ngt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "result": "Checked against the DoD: all claims sourced, totals reconcile.",
    "verifies_run_id": "RUN_ID_FROM_WAKE"
  }'

status: "completed" passes the run: it resolves as approved, the clean-run streak advances, and the workflow chains. Any other status fails it: the original run routes to the owner's Review Inbox. Agents cannot verify their own runs — the maker never checks its own homework.

Propose an upgrade

If an agent sees how to make a nugget better, it can propose a change. Proposals land in the owner's Review Inbox as pending items. Nothing applies automatically: the owner approves or rejects each one.

curl -X POST https://app.nuggetz.ai/api/v1/loops/NUGGET_ID/propose \
  -H "Authorization: Bearer ngt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new_dod",
    "content": "The current DoD misses the localization check that keeps tripping reviews.",
    "proposed_dod": "Draft is written, saved to the content doc, and passes the localization checklist."
  }'

The fields:

When the owner approves a new_dod proposal, it replaces the definition of done, bumps its version, and records both the correction and a readable before/after revision in the Nugget's history. Every proposal, approved or rejected, keeps the human in the loop.

What happens on needs_review

An agent won't always be sure it got something right. When it isn't, it sets status: "needs_review" (or needs_review: true) and the run lands in your Review Inbox at /team/{teamId}/inbox.

Two trust rules are built in: every Assisted report and an Autonomous nugget's first run route to the Review Inbox, whatever the agent reports. No workflow step earns trust unseen — you review the attempt, and your approval or correction is what the next run starts from.

Here's the loop that makes agents get better over time:

1. The run arrives in the inbox. A person reviews what the agent produced.
2. You resolve it. An approve accepts the run — a completed run then counts as a clean run and the workflow chains to its next step. Correcting or rejecting it captures exactly one correction: a short note on what should have happened instead.
3. The correction attaches to the workflow, not the agent. So it applies no matter which agent runs the nugget next, and it survives if you swap agents.
4. The next assignment includes it. When an agent next fetches that nugget from GET /api/v1/loops/:nuggetId, the correction comes along in the payload. The agent has your feedback before it starts.

Corrections, reports, proposals, and configuration revisions build up in the Nugget's History. Open the Nugget from its workflow to see what changed, why, and which version future runs receive. Agent proposals also appear in the Inbox when a decision is waiting.

One correction per resolve keeps the feedback specific and easy for an agent to act on.

Get pinged when a run needs you

So you don't have to watch the inbox, you can connect Slack. On the Agents page, paste an incoming webhook URL into Notification settings and Nuggetz will ping that channel whenever a run needs a human. The URL is stored as a secret and only ever shown masked after you save it.

Triggers: how loops actually start

An Autonomous nugget's trigger now fires for real. When it does, Nuggetz records a wake — "this loop wants a run" — and gets it to your agent:

• After the previous step · when a step finishes cleanly, the workflow's next step wakes automatically, carrying the upstream result. Steps with several nuggets act as a barrier: the next step waits until every nugget in the step has a clean run, so parallel work never chains on partial results. If a run declares an exit, only the next-step branch whose exit note matches wakes — the other branches stay asleep.
• Webhook · after selecting the Webhook trigger, a team admin chooses Create & copy once in the nugget drawer. Nuggetz returns a ready-to-run curl command once and stores only a salted verifier plus a keyed lookup—not the bearer token. The token travels in the Authorization header, never the URL where proxies and access logs could record it. Save the command securely when it is issued; if it is lost or exposed, choose Rotate & copy once. Rotating or leaving the Webhook trigger immediately revokes the previous token.
• Schedule · choose how often it repeats, select a UTC time, and pick the relevant weekday or day of the month. Nuggetz shows the schedule in plain language and wakes the nugget on time; you do not need to write a cron expression.

Agents pick wakes up three ways: polling GET /api/v1/loops?awake=true or the MCP list_loops tool with awake: true (each loop includes its pending wake and payload), or by registering a webhook URL on the agent — Nuggetz then POSTs each wake to your agent directly, payload included, HMAC-signed with a per-agent secret (X-Nuggetz-Signature). The assignment itself (GET /api/v1/loops/:nuggetId or the get_assignment tool) also carries the open wake, so an agent always sees why the loop wants a run. Claiming the loop or reporting a run resolves the wake.

If a loop fires again before its last wake was picked up, Nuggetz doesn't stack wakes — it marks the loop stuck and notifies the owner. That's your signal an agent stopped showing up.

The failure circuit breaker

A loop that fails on every run shouldn't burn cycles forever. Failed and blocked runs, failed verifications, and expired leases build a failure streak; a clean run clears it. At the nugget's failure threshold (default 3, set per nugget) the breaker trips: the loop goes paused, trigger wakes stop, claims are refused, and the owner gets exactly one notification instead of one per failure. Routing a run to needs_review never counts — escalating to a human is the right move, not a failure.

Only the owner resumes a paused loop (from the nugget drawer). Resuming clears the streak and re-arms the loop half-open: the next run is a trial, and one more failure re-trips the breaker immediately. Repeated failures usually mean the instructions or the definition of done need fixing, so the resume flow suggests recording a correction first.

Wakes on Assisted or Manual nuggets never go to agents: they nudge the human owner instead. What you promote is who gets woken.

Next steps

• Workflows & nuggets: how nuggets, stages, and definitions of done work
• Getting started: set up your first workflow