Connect from MCP Clients

Workprentice serves an MCP endpoint at https://workprentice.ai/mcp. Point a client at it with a workspace API key and your agents, sessions, documents, data tables, knowledge bases, boards, and inbox become tools inside that client. You can ask an agent a question and get its answer back without leaving the tool you were already working in.

This is the inbound direction. The outbound one — giving your agents tools from a server you run — is custom MCP servers, and the two share nothing but the protocol.

Connect

Create the key first. In Settings → Workspace → API Keys, choose Create Key and name it after the client you are connecting (claude-code, laptop-desktop). The full key — it starts with wak_ — is shown exactly once, so paste it straight into the client’s configuration. Rotation and revocation are covered in API keys and webhooks.

Then add the server. In Claude Code:

claude mcp add --transport http workprentice https://workprentice.ai/mcp \
  --header "Authorization: Bearer wak_..."

Clients configured from a JSON file, claude_desktop_config.json among them, take the same three facts: the transport, the URL, and the header.

The endpoint speaks MCP 2026-07-28, the stateless revision, and still answers the initialize handshake that earlier revisions use. Either way it is Streamable HTTP over a single URL, so no client needs to know which era it is on and none has to be upgraded before it can connect.

{
  "mcpServers": {
    "workprentice": {
      "type": "http",
      "url": "https://workprentice.ai/mcp",
      "headers": {
        "Authorization": "Bearer wak_..."
      }
    }
  }
}

Two header forms, one key

Webhooks authenticate with X-API-Key; MCP uses the Authorization: Bearer form of the same wak_ key. A client can also connect and list the tools without any credentials — tool names and descriptions are not secret — so the first sign of a missing or wrong header is a tool call that fails rather than a connection that does.

Ask the client for whoami first. It answers with the user, workspace, and organization the key resolves to, which is the quickest proof the header landed where you meant it to.

What you can do

Forty-one tools, curated rather than generated from the API. They group like this:

Tools	What they reach
whoami, list_agents, get_agent, get_agent_capabilities	Who the key is, which agents the workspace has, and what each one carries — skills, standing assignments, memory keys. Each agent entry includes its A2A endpoint.
ask_agent, create_session, send_message, wait_for_reply, get_session, get_transcript, list_sessions, search_sessions, stop_session	Conversations: start one, keep it going, read it back, search full text across every session in the workspace, stop a run that has gone the wrong way.
list_knowledge_bases, browse_knowledge, read_knowledge_file, write_knowledge_file, list_agent_memory, read_agent_memory	Knowledge bases as a browsable file tree, and what an agent has learned in memory. Listings show memory keys and titles; read one by key for its value.
list_documents, read_document, create_document, update_document, comment_on_document, list_data_tables, get_data_table, query_data_table, insert_data_table_rows, update_data_table_rows, delete_data_table_rows, list_work_products, get_work_product	Documents and the rest of the work products agents produce, plus data tables with the same filter, sort, group, and aggregate queries the app uses. A comment on a document can wake the agent responsible for it.
run_assignment, list_assignments, get_assignment, list_boards, get_board, create_board_task, update_board_task, list_inbox, respond_to_inbox	Standing assignments and headless runs, boards and their tasks, and the inbox — including answering a question an agent is blocked on.

What that turns into at the prompt:

• Delegate without switching tools — “Ask my research agent what moved in the competitive landscape this week, then summarize its answer for me.”
• Query the data an agent maintains — “Query the Pipeline table for deals over $50k that slipped a quarter, grouped by owner.”
• Pull in what the team already wrote — “Read the onboarding runbook in the Engineering knowledge base and tell me which steps are stale.”
• Put work where the team tracks it — “Add a task to the Content board for the launch brief and assign it to the content agent.”
• Unblock an agent mid-run — “Answer the question my ops agent left in my inbox: use the FY26 numbers.”

Waiting for a reply

An agent turn takes seconds to minutes and MCP calls are request/response, so the reply-bearing tools wait. ask_agent holds for 60 seconds by default; send_message returns as soon as the message is queued unless you give it a wait_seconds. Either way the ceiling is 300 seconds.

When a wait runs out the call still returns normally, with status: "timeout", the session id, a last_seqnum watermark, and whatever messages did arrive. The client hands that watermark back to wait_for_reply and keeps waiting — the handoff is described in the tool definitions, so clients do it on their own and you see one question and one answer that happened to take a while. The other statuses are replied, completed, running, cancelled, and error.

Whatever comes back, the conversation is a real session. Open it in Workprentice to see the full log — every thought, tool call, and decision — exactly as if you had started the conversation in the app.

What the key can reach

A workspace key is powerful, and the surface it opens is worth understanding before you paste one into a client.

• One key, one workspace. The key is pinned to the workspace it was created in and acts as the person who created it. An agent nobody shared with that person stays invisible to the key.
• The same checks as the app. Every tool call re-enters the same authenticated API the web app uses, so role checks, workspace scoping, and the audit trail apply identically. The tools add reach, not authority.
• Administration is out of scope by design. API key and token management, integration and connection setup, organization membership, sharing and grants, and agent creation and deletion are all absent from the tool surface. A leaked key cannot use MCP to widen its own reach.
• Results are capped. Each call returns at most 50,000 characters, with a marker telling the client to narrow the request with limit and offset rather than leaving it to guess at a silent cut.
• Revocation is immediate. Revoke or rotate the key in Settings → Workspace → API Keys and the client stops working on its next call.

Patterns that work

• One key per client — a key for the laptop, another for the desktop, another for a script. Losing one machine costs one revocation.
• Ask, then open the session — take the short answer in the client, and open the session id it returns in Workprentice when you want to see how the agent got there.
• Let the agent do the reading — ask_agent puts the workspace’s whole toolkit behind a single call, which beats stitching together six read tools when the question is really “what happened with X.”