Architecture
The pieces of Median, what runs where, and how a message travels from your customer to the agent, your tools and your team.
The pieces
| Piece | Where it runs | What it does |
|---|---|---|
| Backend | Median’s servers. api.median.sh answers the REST API, MCP and OAuth. The widget reaches the same backend over a WebSocket, see CSP |
Stores conversations, customers, knowledge and settings. Runs the agent, the REST API, the MCP server and webhooks |
| Dashboard | median.sh |
Where your team works the inbox and changes settings. How to use it is in the help center |
@mediansh/widget |
Your site, in the browser | The support widget, the support modal, the contact form and the feedback panel |
@mediansh/agent-tools |
Your server | Serves your custom tools, signs your users’ identity, and signs visitors in to your public site |
| CLI | Your terminal, or a coding agent’s | The management API as commands |
| Public site | <slug>.median.website, or your own domain |
Your help center, built from your knowledge base, plus a support page and a feedback board |
| Chat bot | Median’s servers | Discord tickets, the Slack and Discord mirrors, the assistant and commands in Slack and Discord, and Discord feedback channels |
The REST API, the CLI, MCP clients, the in-app assistant and the Slack and
Discord /c command all go through one
capability list. A capability has one name on every
surface, runs with the caller’s role, and says whether a model acting for
somebody has to ask them first.
A message, end to end
A customer writes in
From the widget, your public site’s support page, email, a Discord ticket, or your own front end on the messaging API. The widget holds a live connection to the backend, so replies arrive without polling. Each message lands in one conversation, tied to one customer.
The agent takes a turn
While the agent has the conversation, every customer message starts a turn. It reads the thread, what is known about the customer, and your team’s notes, then decides what to do.
It searches your knowledge
The question is embedded and matched against your documents, a few passages at a time. A passage from a page with a published address can be cited with a link.
It calls your tools
Median’s servers send a signed POST to your tool route. Your route
checks the signature, runs the function and answers with JSON. A high
risk call waits for a teammate first, and a reviewed one for the
automated reviewer. See How tool calls run.
It replies, or hands off
The reply goes back on the channel the customer used. When it cannot finish, it hands the conversation to your team with a briefing, and the thread waits under Needs a person in the inbox.
Trust boundaries
| Between | How it is secured |
|---|---|
| Browser and backend | The widget sends the public median_pk_ key, which can only start and read the browser’s own conversations, and send feedback and crash reports. A signed in user is proven with an identity signature made on your server |
| Backend and your tool route | Each request carries median-signature: t=<ms>,v1=<hex>, an HMAC-SHA256 made with a secret derived from your Median key. Requests time out after 10 seconds |
| Backend and your webhook endpoint | The same signature scheme, with its own derived secret |
| Your server and the REST API | Authorization: Bearer with a median_key_ Median key, or an OAuth token for one person. See API overview |
| MCP clients | OAuth with PKCE, where the client acts as the person who approved it, or a Median key, which acts as the organization |
The Median key never leaves your server. Everything the browser holds is derived from it and safe to expose.
Where data lives
| Data | Kept in | Read by |
|---|---|---|
| Conversations, messages, files | The backend | The inbox, the agent, the API, webhooks |
| Customers and what was learned about them | The backend | The inbox and the agent. Your tools get visitor: identity, name and email only |
| Knowledge documents | The backend. Synced sources are copied in and kept current | The agent, your public site, the API |
| Tool definitions | Your server. Median keeps a synced copy of the manifest | The agent |
| Tool results | Stored on the conversation | Your team. The agent, for the calls it made. A tool a teammate runs by hand is not shown to it |
Limits worth knowing
| Limit | Value | More |
|---|---|---|
| Tools per organization | 20, across up to 10 endpoints | Custom tools |
| Tool call timeout | 10 seconds | How tool calls run |
| Message length | 4,000 characters | Errors and limits |
| API rate limits | By plan | Rate limits |
Something not behaving the way this page says? The help center’s troubleshooting matches symptoms to causes, and Tool errors covers every error from a tool endpoint.