Skip to content
SVEDA
Menu

USE CASE

Your MCP. Their turn.

Host MCP is not a second client you wire by hand. URL and token go on POST /sveda/embed/token. The runtime lists tools and calls them during the turn.

Get started MCP & tools

URL + token

required together on embed mint

http(s)

host_mcp_url must be HTTP

Bearer

outbound Authorization on every call

The challenge of wiring MCP by hand

Host tools should run in the agent loop, not in a second client the frontend has to babysit. Without Sveda, teams open an MCP session per visitor, copy tokens into the browser, and write list/call glue that never quite matches the turn. The handshake belongs on POST /sveda/embed/token. The runtime lists tools and executes them.

A client per server

Each MCP origin becomes a custom session, a header pile, and a reconnect path that the product then has to stream around.

Credentials in the browser

Host MCP tokens leak into frontend config. Visitor scope is whoever last pasted the secret.

Tools off the turn

list_tools runs in a sidebar. execute is a separate HTTP hop. The model never sees the catalog that the host actually exposed.

How Sveda solves it

Pass host_mcp_url and host_mcp_token together when minting the embed token. sveda-server stores them per visitor_id when a host API key is configured, lists tools over HTTP, and executes them in the loop with Bearer auth.

Handshake together

URL without token, or token without URL, is rejected. The pair is the attachment. http:// and https:// only.

  • POST /sveda/embed/token accepts host_mcp_url and host_mcp_token
  • Both required together — 422 if only one is set
  • host_mcp_url must be a valid HTTP(S) URL, no whitespace, max 2048 chars
  • Stored per visitor_id when the host API key is configured
  • The JS client still only sends the embed token

Runtime list and execute

The agent loop owns tools/list and tools/call. You do not open a second MCP client in the page.

  • Runtime initializes the HTTP MCP session
  • list_tools becomes the catalog the model sees
  • execute runs inside the turn, not beside it
  • Frontend tools stay on SvedaClient; host tools stay on HTTP MCP
  • Deferred pools can hide behind search_agent_tools

Outbound auth and context

Every MCP request carries Authorization: Bearer plus optional page and chat headers from the turn.

  • Authorization Bearer uses the host_mcp_token
  • Optional x-sveda-page-context from the turn (JSON, max 24KB)
  • Optional x-sveda-chat-id when the session has a chat id
  • mcp-protocol-version on the wire
  • Host tools never need a browser-held MCP secret

HANDSHAKE

One mint. URL and token together.

The embed-token route is the MCP attach surface. Send host_mcp_url and host_mcp_token on the same JSON body as visitor_id. The runtime refuses a half pair. It refuses non-HTTP URLs. When the host API key is configured, credentials are stored against that visitor_id.

The browser still sends x-sveda-embed-token. It does not send the MCP token. That is the point of minting on the host.

See embed tokens and the embed token docs for the request shape.

POST /sveda/embed/token together 
{
  "visitor_id": "kirill",
  "host_mcp_url": "https://host/mcp",
  "host_mcp_token": "…"
}

422 if only one field is set

http(s) only · stored per visitor_id

HOST MCP
tools/list catalog
tools/call execute

Authorization: Bearer …

x-sveda-page-context

x-sveda-chat-id

tool.result in-stream

LIST + EXECUTE

Listed in the loop. Executed in the turn.

sveda-server lists tools over HTTP and executes them while the stream is open. Outbound calls use Authorization Bearer with the token from the handshake. If the turn carried page context or a chat id, those headers go with the call: x-sveda-page-context and x-sveda-chat-id.

This is not a chatbot SaaS connector gallery. You run the MCP server. The runtime is the client. The visitor never holds the host MCP token.

The tools docs cover builtins plus host MCP. The code agent page covers index tools on the same loop.

Related

Product copilot

Mint the embed token on the host. Attach SvedaClient. Keep the app.

Code agent

Index tools on the same runtime that executes host MCP.

Model failover

Host tools stay attached when the model list walks.

MCP & tools

Host HTTP MCP plus builtins and frontend tools.

Embed token

host_mcp_url and host_mcp_token ride the mint.

Tools docs

Host MCP HTTP attachment rules, list, and execute.

Embed token docs

Paired URL and token, x-sveda-host-key, visitor_id.

Attach MCP on the mint.

host_mcp_url and host_mcp_token together. The runtime lists tools, executes them, and sends Bearer.

Get started