The builder for agents: MCP

Everything the builder does in the dashboard, it also does for your agent or script: add knowledge, connect a channel, change the character, create an action or a schedule. The entry point is an MCP server.

This is the entry to the BUILDER, not to the agent itself

Here another program builds and changes agents. If you want Claude, Cursor or another bot to talk to your agent — ask it questions and give it tasks — that's a different entry with a different key: Agent as a tool: MCP and A2A.

There are three tools, and only one of them CHANGES anything — constructor, which is the same conversation as in the dashboard: there's no separate catalog of "methods" to fall behind. The other two are read-only windows, so that an agent that has just connected doesn't talk about a bot it hasn't seen.

https://api.youselfbot.com/v1/api/mcp

The builder key is not a bot key

MCP needs a builder key (ck_…). It's deliberately separate from the bot's keys:

Key	What it opens	Where it lives
`pk_…` public	the chat window on your site	in your page's HTML
`sk_…` bot secret key	integrations of one bot: chat, knowledge, operators	in your backend
`ck_…` builder key	management of all the workspace's agents — MCP and the management API	only in your agent clients
`ak_…` agent access key	a conversation with one agent as a visitor — agent as a tool	in the program you gave access to

An integration key baked into someone's backend shouldn't be able to rebuild the bot — that's why sk_ isn't let into the builder. The limits of ck_: it manages agents as the owner would, but doesn't pay, doesn't delete agents and doesn't touch the team.

Way 1 — through the browser (the simplest)

Clients that support pairing don't ask for a key: they bring you to the dashboard themselves. The flow:

the client calls POST /v1/mcp-pair/start and shows you a link;
you open it — it's the app.youselfbot.com/connect page, which says who exactly is asking to connect;
you click Allow — and the client picks up its key itself (GET /v1/mcp-pair/poll).

The key is never shown on screen and never goes through the clipboard. Approving a second client doesn't disconnect the first.

A minimal example for a script:

bash

START=$(curl -s -X POST https://api.youselfbot.com/v1/mcp-pair/start \
  -H "Content-Type: application/json" -d '{"device":"my script"}')
echo "Open: $(echo $START | jq -r .verify_url)"
# after "Allow" in the browser:
curl -s "https://api.youselfbot.com/v1/mcp-pair/poll?code=$(echo $START | jq -r .code)&secret=$(echo $START | jq -r .secret)"
# → {"status":"ok","constructor_key":"ck_…"}

Way 2 — a key from the dashboard

Account → MCP for agents → New builder key. The key is shown once, next to a ready-made command for Claude Code:

bash

claude mcp add --transport http youselfbot \
  https://api.youselfbot.com/v1/api/mcp \
  --header "Authorization: Bearer ck_YOUR_KEY"

The button reissues: previous builder keys stop working that very moment.

You can also ask for the same key in words — in the conversation with the builder in the dashboard: "give my Claude full access". It will issue a key (showing it once) together with the setup for your program; a key issued this way does not revoke the previous ones — unless you ask "issue a new one and revoke the old ones". "Revoke the builder key" revokes them all. The configuration for any client that reads mcpServers:

json

{
  "mcpServers": {
    "youselfbot": {
      "type": "http",
      "url": "https://api.youselfbot.com/v1/api/mcp",
      "headers": { "Authorization": "Bearer ck_YOUR_KEY" }
    }
  }
}

Tools

Tool	What it does	Arguments
`agents`	Which agents are in the dashboard: id, name, how many knowledge sources and channels. A key issued for one bot is marked separately.	—
`incidents`	What's broken in the agent — in the same words the owner reads, together with how to fix it.	`agent_id`
`constructor`	A conversation with the builder: the only thing that changes anything.	`message`, `thread`

The order isn't accidental: first look at what you're working with, then at what hurts, and only then make changes. Changes apply immediately, so ask a person before anything irreversible (deleting an agent, disconnecting a channel).

The `constructor` tool

Argument	Required	What it means
`message`	yes	What to do or ask — in plain language, as in the dashboard.
`thread`	no	Thread identifier. Same thread — the builder remembers the previous messages.

The response is the builder's text; button options are appended to the end of the text. Conversations through MCP live separately from the conversation in the dashboard.

For changes customers will see straight away, that can't be undone, or whose effect lands in someone else's system, the builder asks first. In that case the response ends with a line in square brackets: what's waiting for confirmation and where to reply — into the same conversation (the same thread, or without one if there wasn't one) with the message "yes".

The platform remembers consent within the conversation: a "yes" sent with a different thread is a word without a question, and the builder will ask again. So keep one thread per task. After "yes" it does exactly what it asked about, the first time.

Ask a person before replying "yes": the key acts on behalf of the workspace owner.

What a key can't do

A few decisions stay with the owner and can't be made with a key at all — the builder refuses right away, without asking for consent, and says the person does this themselves in the dashboard:

inviting a person to the dashboard;
handing an agent over to another person, cancelling a handover, accepting or declining someone else's agent;
restoring a deleted agent.

Simultaneous calls

Turns in one conversation (one thread) run one after another: a call sent while the previous one is still running waits for it and runs after. If the previous one takes too long (reading a large site), the second one answers that the conversation is still busy and nothing was changed — send it again. Run independent tasks with different threads: they don't wait for each other.

If your client stopped waiting for the response (its own timeout), the turn on our side isn't cut off: it runs to the end (up to three minutes), and its response — together with what it applied — arrives at the start of the response to the next call in the same thread. So after a timeout, don't blindly repeat the same change: send the next message (even just "what got done?") — and you'll see the result of the previous one.

A repeated call

A program that didn't wait for the response and sent the same request again leaves no duplicates: the same knowledge text isn't added a second time (the builder answers that such a source already exists), and the same changing call isn't performed twice in a row within one turn.

The same builder without an MCP client — a single HTTP call:

bash

curl -sS https://api.youselfbot.com/v1/dashboard/builder \
  -H "X-Bot-Key: ck_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"message":"add knowledge: pickup from 10 to 19"}'

Protocol and limits

The transport is Streamable HTTP: one POST — one JSON-RPC message, the response is application/json; GET returns 405. The server understands the same two spec eras as the agent's MCP server: the current 2026-07-28 (no handshake, the client's version and capabilities are in params._meta and in the MCP-Protocol-Version, Mcp-Method, Mcp-Name headers, server/discover is available) and the earlier 2025-03-26 – 2025-11-25 with initialize. You don't need to switch anything.

Requests from a page in a browser (with another site's Origin header) are rejected with 403: a builder key doesn't belong in a page.

The rate limit is per workspace, not per address the request came from: twelve builder messages (constructor) per minute. The handshake, the tool list and reads (agents, incidents) don't use up this quota — they have their own, more generous one.

The thirteenth message within a minute gets a tool response with isError: true, not a 429 code: it says in words that this is the rate limit, that the message was not performed and nothing was changed, and how many seconds to wait before sending it again (the same time is in the Retry-After header). If your program adds knowledge one page at a time, put several tasks into one message — that way you won't hit the limit.

An agent that manages itself

A platform bot can connect external MCP servers — and nothing stops you from connecting this one to it. Tell the builder:

Connect the youselfbot MCP server at https://api.youselfbot.com/v1/api/mcp with the token ck_…

— and the agent will be able to ask the builder to change itself: add knowledge it was missing, set a reminder, turn off an action that broke.

The key means control of the workspace

Whoever has ck_… controls your agents. Don't put it in page code or in repositories; if it leaks — Account → New builder key (or tell the builder "revoke the builder key"): the old ones stop working that same second.

With a builder key, a program does the same things with agents that you do in the conversation. What it can't do, even with the key: buy a plan or credits, issue itself another key or allow another program to connect, change the email or delete the account, manage the team, delete an agent or reissue its keys, reply to a customer in "Conversations", approve an action that's waiting for permission. These stay with the person signed in to the dashboard.

The builder for agents: MCP ​

The builder key is not a bot key ​

Way 1 — through the browser (the simplest) ​

Way 2 — a key from the dashboard ​

Tools ​

The constructor tool ​

When the builder asks for consent ​

What a key can't do ​

Simultaneous calls ​

A repeated call ​

Protocol and limits ​

An agent that manages itself ​

The builder for agents: MCP

The builder key is not a bot key

Way 1 — through the browser (the simplest)

Way 2 — a key from the dashboard

Tools

The `constructor` tool

When the builder asks for consent

What a key can't do

Simultaneous calls

A repeated call

Protocol and limits

An agent that manages itself