Skip to content

MCP Server

Junior has a remote MCP server at /api/mcp. An MCP client, such as Claude Code, can use it to read your Junior Conversations, Inbox items, and Automations. The client signs in through your Junior dashboard with Google. It can see only the Conversations that you started or take part in.

Only the conversations:write scope starts agent work. With it, a client can start a Conversation and send messages as you. No tool answers an Inbox item or runs an Automation.

  • The app must mount the dashboard with Google sign-in required. When the dashboard is disabled, or dashboard.authRequired or JUNIOR_DASHBOARD_AUTH_REQUIRED is false, Junior does not mount /api/mcp.
  • The app must know its public URL. Set dashboard.baseURL or JUNIOR_BASE_URL. On Vercel, Junior uses the production URL of the project when you do not set one. Preview deployments also use the production URL. To connect a client to a preview deployment, set JUNIOR_BASE_URL for that deployment.
  • Your MCP client must support OAuth with Client ID Metadata Documents (CIMD). Junior does not support Dynamic Client Registration.

In the dashboard, open Settings and select MCP. The page shows the server URL, the Claude Code command, and a JSON config for other clients.

Add Junior as an HTTP MCP server:

Terminal window
claude mcp add --transport http junior https://<your-domain>/api/mcp

Start Claude Code, run /mcp, select junior, and select Authenticate. Claude Code opens your browser.

  1. Sign in with Google if the dashboard asks you to.
  2. Read the consent page. It shows the client name, the host that publishes the client (for example claude.ai), and each scope that the client asks for.
  3. Select Allow only if you started this connection.

The browser returns to Claude Code, and the server shows as connected.

Ask Claude Code to list your Junior Conversations:

Use the junior MCP server to list my conversations.

Claude Code calls the searchConversations tool. The result shows up to 50 Conversations, newest activity first. Each one has its title, status, viewer state, location, timestamps, and a dashboard link when the dashboard URL is known.

Then ask for one Conversation:

Use junior to summarize my latest conversation.

Claude Code calls getConversation. It returns the summary and the last assistant reply, not the full transcript.

You can also check discovery without a client:

Terminal window
curl -i https://<your-domain>/api/mcp -X POST
curl https://<your-domain>/.well-known/oauth-protected-resource/api/mcp

The first request returns 401 with a WWW-Authenticate header. The second request returns the resource metadata, with every scope in scopes_supported.

A client gets only the tools of the scopes that you allow. A client that does not ask for a scope asks for all of them.

Scope Tools Effect
conversations:read searchConversations, getConversation, listConversationMessages Read the Conversations that you started or take part in.
conversations:manage archiveConversation, archiveDoneConversations, pinConversation, setConversationAutoArchive, setConversationSubscription, markConversationRead, stopConversation, cancelQueuedMessages Archive a Conversation, pin, subscribe to, or mark it read for you, set its auto-archive, stop its running Turn, or drop its queued messages.
conversations:write createConversation, sendMessage Start a Conversation or send a message as you. Junior starts a Turn for it.
inbox_items:read searchInboxItems, getInboxItem Read the Inbox items that you can see.
automations:read searchAutomations, getAutomation Read the Automations that you can see, and their runs.

Junior also accepts review_items:read, the old name of inbox_items:read, so clients and grants from before the rename keep working.

getConversation returns metadata, including the summary, the last assistant reply, and the messages that no Turn has read yet. When a Turn waits for you to connect an account, it also returns the authorization link. Pass a cursor as after to get the messages after that point instead of the last reply. Each result has a new cursor. listConversationMessages returns the user and assistant messages, newest last, 10 at a time by default. Pass its nextCursor as before to read older messages. Tool calls are not included.

Archive applies to everyone in the Conversation. Pin, subscription, the auto-archive choice, and read position are yours. setConversationSubscription with subscribed: false removes a Conversation from only your feed. Your next mention of Junior in it subscribes you again. When the last subscriber unsubscribes, the Conversation is archived for everyone. But when any person pins a Conversation or turns its auto-archive off, auto-archive does not archive it. archiveDoneConversations archives your done Conversations once, the same as Archive done now in Settings. markConversationRead marks every message read when you omit lastReadSeq.

createConversation starts a private Conversation by default. Pass title to name it. When you omit title, Junior generates one from the message. createConversation and sendMessage return when Junior accepts the message, not when Junior answers. Both return the messages that no Turn has read yet. A message sent while a Turn runs waits for that Turn. To add it to the running Turn at its next safe step, pass delivery: interrupt to sendMessage. Your message has the same messageId in these results and in the transcript. To read the reply, call getConversation with after set to the returned cursor. Call it again with the newest cursor until turnActive is false and hasMore is not set. turnActive is true while a Turn runs or waits to start. status is needs_input, working, or done, and needs_input can show while a Turn runs; see Conversations. treeState is your viewer state: needs_you, working, or done over the Conversation and its child agents. A list should show treeState, not status. To retry a send without sending the message twice, pass the same idempotencyKey.

stopConversation stops the running Turn and drops the messages that wait for it. cancelQueuedMessages drops the waiting messages and lets the running Turn continue. Neither tool starts a new Turn. Inbox item and Automation results include a dashboard link. Answer an Inbox item or change an Automation there.

  • A connection keeps the scopes that you allowed. To change them, connect the client again.
  • Access tokens last 1 hour. Your client refreshes them for you. Each refresh token works once.
  • A connection ends 30 days after you allow it, even when the client refreshes its tokens. Then connect the client again.
  • Each request checks the allowed domains again. If your domain is removed, the connection stops working.
  • Personal tokens do not work on /api/mcp. Only tokens from this OAuth flow work.
Symptom Cause and fix
404 on /api/mcp The dashboard is disabled, or it does not require sign-in. Configure the dashboard with sign-in required.
“This app cannot connect” The client did not send a valid CIMD client ID, or its redirect URI is not in its metadata document. Update the client, or use another client.
“This sign-in request expired” The request is older than 10 minutes or was already used. Start the connection again from the client.
The client asks you to connect again The connection reached its 30-day limit, or Junior revoked it. Authenticate again.
A tool is missing from the client The connection does not have the scope of that tool. Connections made before a scope existed do not get it. Authenticate again and allow the scope.

Read Conversations to learn which Conversations you can see and why.