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. To publish one agent as a server with tools you write, and sign in to it rather than paste a key, see Give an Agent an API.

Connect

Create the key first. In Settings → Workspace → API keys, choose New API key (Create your first API key in an empty workspace) 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

The tools are the workspace’s own API, grouped into toolsets. Every tool a client is served lands in its model’s context on each request, so a plain https://workprentice.ai/mcp serves only core: the tools most work goes through, from asking an agent a question to creating an assignment. Add toolsets to the URL for more. core is always included.

# Core plus boards and skills
claude mcp add --transport http workprentice \
  "https://workprentice.ai/mcp?toolsets=boards,skills" \
  --header "Authorization: Bearer wak_..."

# Everything
claude mcp add --transport http workprentice \
  "https://workprentice.ai/mcp?toolsets=all" \
  --header "Authorization: Bearer wak_..."

The full set you can choose from:

Toolset	Covers	Tools
core	The tools most work goes through, served by default.	whoami, list_agents, get_agent_capabilities, ask_agent, send_message, wait_for_reply, get_transcript, run_assignment, read_knowledge_file, write_knowledge_file, update_board_task, list_assignments, get_assignment, create_assignment, update_assignment, get_agent, create_agent, update_agent, list_data_tables, get_data_table, query_data_table, insert_data_table_rows, update_data_table_rows, delete_data_table_rows, list_boards, get_board, list_board_tasks, create_board_task, list_documents, create_document, read_document, update_document, comment_on_document, list_sessions, get_session, create_session, stop_session, search_sessions, search, list_inbox, respond_to_inbox, list_work_products, get_work_product, list_agent_memory, read_agent_memory, list_knowledge_bases, browse_knowledge
agents	Agents, their integrations, memory, and stored files.	whoami, list_agents, get_agent_capabilities, get_agent_storage, delete_agent_storage, delete_agent_storage_version, get_agent, list_agent_revisions, get_agent_revision, restore_agent_revision, list_agent_runs, create_agent, update_agent, update_agent_personality, enable_agent_integration, disable_agent_integration, enable_agent_skill, disable_agent_skill, archive_agent, unarchive_agent, delete_agent, list_agent_memory, read_agent_memory, write_agent_memory, delete_agent_memory, list_agent_memory_revisions, get_agent_memory_revision, restore_agent_memory_revision, get_agent_dreamlog, get_agent_reflections, set_agent_reflection_schedule
assignments	Standing assignments, their runs, and completion hooks.	run_assignment, list_hook_definitions, get_hook_definition, upsert_hook_definition, list_assignments, get_latest_assignment_runs, get_assignment, list_assignment_runs, create_assignment, update_assignment, archive_assignment, unarchive_assignment, delete_assignment, list_assignment_revisions, get_assignment_revision, restore_assignment_revision
sessions	Conversations, transcripts, forks, and comments on them.	ask_agent, send_message, wait_for_reply, get_transcript, get_session_comments, create_session_comment, create_session_comments, resolve_session_comment_thread, delete_session_comment, commit_session_comment_thread, list_sessions, get_session, update_session, delete_session, archive_session, unarchive_session, create_session, stop_session, list_available_session_skills, list_available_session_integrations, activate_session_skill, deactivate_session_skill, fork_session, list_session_forks, search_sessions, submit_message_feedback, delete_message_feedback, list_session_children
documents	Documents, comments, suggestions, and work products.	edit_document, search_documents, list_documents, create_document, duplicate_document, read_document, update_document, archive_document, unarchive_document, delete_document, create_document_from_work_product, list_document_revisions, get_document_revision, restore_document_revision, get_document_comments, comment_on_document, resolve_document_comment_thread, delete_document_comment, get_document_suggestions, create_document_suggestion, accept_document_suggestion, reject_document_suggestion, list_work_products, get_work_product, list_session_work_products, rename_work_product, list_work_product_revisions, get_work_product_revision, restore_work_product_revision
data_tables	Data tables, their rows, schemas, and snapshots.	list_data_tables, create_data_table, duplicate_data_table, get_data_table, update_data_table, archive_data_table, unarchive_data_table, delete_data_table, update_data_table_schema, delete_data_table_columns, query_data_table, insert_data_table_rows, update_data_table_rows, upsert_data_table_rows, delete_data_table_rows, create_data_table_snapshot, list_data_table_snapshots, restore_data_table_snapshot
knowledge	Knowledge bases and their files.	read_knowledge_file, write_knowledge_file, list_knowledge_bases, create_knowledge_base, get_knowledge_base, update_knowledge_base, archive_knowledge_base, unarchive_knowledge_base, delete_knowledge_base, browse_knowledge, delete_knowledge_file, list_knowledge_file_revisions, get_knowledge_file_revision, restore_knowledge_file_revision, create_knowledge_folder, delete_knowledge_folder, move_knowledge_path
skills	Workspace and agent skills and their files.	read_skill_file, write_skill_file, preview_skill_import, import_skill, preview_skill_upgrade, upgrade_skill, discover_skill_import, preview_skill_import_batch, import_skill_batch, list_skills, list_skill_library, list_selectable_skills, get_skill, get_skill_consumers, create_skill, update_skill, archive_skill, unarchive_skill, delete_skill, list_skill_revisions, get_skill_revision, restore_skill_revision, promote_skill, browse_skill, delete_skill_file, list_skill_file_revisions, get_skill_file_revision, restore_skill_file_revision, create_skill_folder, delete_skill_folder, move_skill_path, list_agent_skills, get_agent_skill, create_agent_skill, update_agent_skill, archive_agent_skill, unarchive_agent_skill, delete_agent_skill, list_agent_available_skills
boards	Boards, columns, and tasks.	update_board_task, list_boards, create_board, get_board, update_board, archive_board, unarchive_board, delete_board, list_adoptable_assignments, set_board_rules, create_board_column, update_board_column, move_board_column, delete_board_column, create_board_task, adopt_board_assignment, release_task_assignment, list_board_tasks, get_board_task, delete_board_task, release_board_task, list_board_subtasks, get_board_task_dependencies, add_board_task_dependency, remove_board_task_dependency
issues	Issues, triage, and issue types.	scan_issue_events, get_issue, list_issue_events, list_issues, report_issue, create_issue, acknowledge_issue, start_issue, close_issue, snooze_issue, unsnooze_issue, accept_issue, decline_issue, merge_issue, list_issue_types, upsert_issue_type, get_issue_comments, create_issue_comment, create_issue_comments, resolve_issue_comment_thread, delete_issue_comment
channels	Channels, their members, and messages.	list_channels, create_channel, get_channel, archive_channel, unarchive_channel, update_channel, list_channel_messages, post_channel_message, set_channel_reaction, list_channel_members, add_channel_member, update_channel_member, remove_channel_member, list_direct_messages
inbox	The caller’s inbox and the workspace activity feed.	list_activity, count_inbox, list_waiting_inbox, list_inbox, update_inbox_items, get_inbox_item, mark_inbox_item_read, respond_to_inbox, answer_inbox_question, forward_inbox_item, archive_inbox_item, snooze_inbox_item, unsnooze_inbox_item, mark_inbox_item_unread, set_inbox_item_priority
apps	Apps, their versions, and storage.	list_apps, get_app, create_app, duplicate_app, update_app, archive_app, unarchive_app, delete_app, list_app_versions, get_app_version, create_app_version, get_app_storage_value, set_app_storage_value, delete_app_storage_value, get_app_storage_keys
guilds	Guilds and their enlistments.	list_guilds, get_guild, enlist_guild, list_guild_installs, get_guild_install, disband_guild
search	One ranked search across every kind of thing.	search

A tool outside a connection’s toolsets answers with the toolset to add, and the server’s instructions list every toolset, so a model can tell you which URL gets it what it needs. Every tool that deletes data, overwrites stored content with no revision to restore, or resets fields or list entries you leave out is marked destructive, so a client that asks before running such tools will ask before those.

Importing and upgrading skills from GitHub or skills.sh keeps the review step the app has. preview_skill_import and preview_skill_upgrade pin a commit and list what the scan found, each warning with a code. import_skill and upgrade_skill succeed only when every warning code is listed in their acknowledgements. If your client asks before running them, the call it shows you names exactly the warnings you are accepting. If it doesn’t, because auto-approve is on or your key was given to an agent, warnings are accepted in your name without you seeing them. Blocked findings never import. Where an admin has limited accepting warnings to admins, or turned it off, the preview says whether you can, and the import is refused if you can’t. An imported skill starts inactive. Both writes are marked destructive, and the skill’s import record notes that the approval came through MCP and which key made it.

For a list, such as the entries in an APM lockfile, discover_skill_import lists the skills in a repository or folder, preview_skill_import_batch reviews up to 25 at once, and import_skill_batch imports the ones you accept, each under the same rules as a single import. Ask for the list preview without file text so every skill’s review fits in the result, and preview one skill on its own when you want to read it.

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 connections and credentials, organization membership and policy, billing, and sharing and grants are all absent from the tool surface. A leaked key cannot use MCP to widen its own reach.
• It can change the workspace. The key can create, edit, and delete agents, assignments, skills, and the rest of the workspace’s content, just as it can through the API. Give a key only to a client you trust with that.
• Results are capped. Each call returns at most 50,000 characters, with a marker saying the result was cut, and, on tools that page, telling the client to narrow the request with limit and offset.
• Agent turns are rate-limited. A workspace can start 100 fresh agent turns an hour over MCP, counted over a sliding hour and shared with every agent API in the workspace. The cap exists for a looping or misbehaving client; a person asking questions from an editor will not come near it.
• 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.”