Give an Agent an API

An agent’s API turns it into an MCP server of its own. You decide which tools it publishes and what each one asks the agent to do; a client that connects sees those tools and nothing else. Behind every call the agent runs an ordinary session with its whole toolkit — knowledge, skills, memory, integrations — and the answer it writes is the tool’s result.

This is different from the workspace MCP endpoint, which exposes your workspace’s objects behind an API key. An agent’s API exposes one agent, behind a sign-in: a person connects as themselves and approves the client once, and a machine uses a credential the agent’s owner minted for it.

Turn it on

Open the agent and choose the API card in its configuration rail. Switching Serve on publishes the agent at

https://workprentice.ai/mcp/agents/<agent-id>

The card shows Serving while it is on; open it for the address with a copy button, and, under Details for clients, the discovery document and issuer for a client you point at them by hand. The agent’s owner can turn the API on or off, as can a workspace admin once the agent is shared with the workspace; anyone who can edit the agent can add tools. Personal agents, templates, and archived agents are never served, and a paused agent (its Automated runs switch is off) stops serving until it is resumed.

Add tools

Each tool is a name the client calls, a description the client’s model reads to decide when to use it, the parameters it accepts, and a prompt the agent runs when the tool is called. Parameters are addressed in the prompt in uppercase:

Research {{ACCOUNT}} across your knowledge and connected tools and reply
with a one-page brief: who they are, what we know, and the next step.

Tool and parameter names use lowercase letters, digits, and underscores, start with a letter, and run to at most 64 characters. A parameter without a default is required. The editor refuses a prompt that names a parameter you did not declare, and one that spells a parameter in lowercase, since that would render as nothing. Every declared parameter must also appear in the prompt: the editor notes one that doesn’t, and saving the tool fails until you use it or remove it.

When a client calls the tool, the agent starts a fresh private session under the name of the person who connected, runs the prompt with the client’s values filled in, and the last thing it says comes back as the result. A call waits up to five minutes; if the agent is still working after that, the result names the session so you can open it and follow along. Results are capped at 50,000 characters.

Switch a tool off to hide it from clients without deleting it.

Connect as yourself

Any client that speaks streamable HTTP and OAuth can connect. It will open a browser tab where you sign in to Workprentice and approve the client for that agent; approve it once and the client keeps working until you disconnect it.

Claude Code

claude mcp add --transport http oracle https://workprentice.ai/mcp/agents/<agent-id>

Then use /mcp inside Claude Code to authenticate. The tools appear under the server name you chose.

Claude Desktop — add a custom connector with the API URL and follow the sign-in it opens.

A client configured by file — most accept an entry of this shape and handle the sign-in on first use:

{
  "mcpServers": {
    "oracle": {
      "type": "http",
      "url": "https://workprentice.ai/mcp/agents/<agent-id>"
    }
  }
}

You can only connect to an agent you could already talk to in Workprentice. The agent’s owner, or a workspace admin for a shared agent, sees every connected app on the API card’s Access tab, with who approved it, and can disconnect any of them. Nobody else sees that list, so if you connected an app to someone else’s agent and want it cut off, ask one of them.

Connect a script

For a service or job that runs without a person, create a machine credential under New credential on the API card’s Access tab. That takes both control of the agent (its owner, or a workspace admin for a shared agent) and the workspace Admin role, because a credential is a workspace-reachable secret like an API key. The client id and secret are shown once. Exchange them for a token, then call the API with it:

TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://workprentice.ai/mcp/agents/<agent-id> \
  https://workprentice.ai/oauth/token | jq -r .access_token)

curl -s https://workprentice.ai/mcp/agents/<agent-id> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"research_account","arguments":{"account":"Acme"}}}'

Tokens last an hour; request a new one when it expires. Calls made with a credential run as the person who created it, and revoking the credential stops them at once.

Call it from another agent

A served agent shows up in the workspace’s Integrations as an Agent API, already installed for every agent in the workspace that can see it. There is nothing to connect or add: a calling agent can use its tools straight away, and each call runs the served agent in its own session. An agent cannot call itself, and a chain of agents calling agents stops after a set number of hops, so a loop cannot run away. Use the Integration access guardrail to keep a particular agent from reaching another.

Limits

• An agent-to-agent chain runs two hops by default, which an admin can raise up to the plan’s ceiling under Guardrails → Collaboration; the call past the cap is refused outright. See Limits.
• Each call is a cold start and counts against the same hourly cap as the workspace MCP endpoint.
• A call waits up to five minutes and returns at most 50,000 characters.
• Access tokens last one hour; a person’s refresh token lasts thirty days.

Disconnecting

Switch Serve off to stop serving at once: every connected app and credential is refused on its next call, and the tools disappear from the workspace’s integrations. Nothing is revoked, so switching Serve back on restores every app and credential as it was. To cut off one client for good and leave the rest, use Disconnect on a connected app or Revoke on a machine credential in the Access tab.