Oshara Docs

Overview

MCP (Model Context Protocol) tools connect your agent to an MCP server — a standardised interface for exposing tools to LLMs. An MCP server can expose many tools; each mcp tool definition in Oshara maps to one specific tool on one specific server.

Setup: define an MCP server

Before defining mcp tools, register the server in your character configuration under mcp_servers:


{
  "mcp_servers": [
    {
      "name": "my-mcp",
      "url": "https://mcp.yoursite.com/call",
      "transport": "streamable_http",
      "headers": {
        "Authorization": "Bearer mcp-service-token"
      },
      "timeout_seconds": 12
    }
  ]
}

MCP server fields

Field	Type	Default	Description
`name`	string	—	Required. Identifier used to reference this server in tool configs.
`url`	string	—	Required. Endpoint URL of the MCP server.
`transport`	`"streamable_http"` \| `"sse"` \| `"http_json"`	`"streamable_http"`	Wire protocol. See comparison below.
`headers`	object	`{}`	Static headers sent with every call (auth tokens, tenant IDs).
`timeout_seconds`	number	`12`	Per-call timeout (2–30 s).
`is_active`	boolean	`true`	Set `false` to disable without deleting.

Transport comparison

Transport	Description	When to use
`streamable_http`	HTTP POST with streaming JSON response (MCP spec default)	Most MCP servers
`sse`	Server-Sent Events stream	Servers that push incremental results
`http_json`	Plain HTTP POST returning a single JSON response	Simple servers without streaming

Define an MCP tool


{
  "name": "search_web",
  "kind": "mcp",
  "description": "Search the web for current information. Use when the user asks about recent events or topics not in the knowledge base.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      }
    },
    "required": ["query"]
  },
  "config": {
    "server_name": "my-mcp",
    "tool_name": "web_search"
  }
}

`config` reference

Field	Type	Description
`server_name`	string	Must match the `name` of an entry in `mcp_servers`.
`tool_name`	string	The tool name as exposed by the MCP server.

Multiple tools from one server

You can define many Oshara tools pointing at different tools on the same MCP server:


{
  "mcp_servers": [
    {
      "name": "integrations",
      "url": "https://mcp.yoursite.com/call",
      "transport": "streamable_http",
      "headers": { "Authorization": "Bearer token" }
    }
  ]
}


[
  {
    "name": "send_email",
    "kind": "mcp",
    "description": "Send an email to the user.",
    "input_schema": { ... },
    "config": { "server_name": "integrations", "tool_name": "send_email" }
  },
  {
    "name": "create_calendar_event",
    "kind": "mcp",
    "description": "Schedule a calendar event.",
    "input_schema": { ... },
    "config": { "server_name": "integrations", "tool_name": "calendar_create" }
  }
]

Per-session MCP headers

For headers that vary per user (e.g. a user-scoped JWT), pass them at session start — they are merged into all MCP calls for that session:


POST /api/agents/agent-session/
{
  "agent": "support-bot",
  "mcp_headers": {
    "X-User-Id": "u_123",
    "X-Org-Token": "org-jwt-here"
  }
}

Nest a map under a server’s name to scope headers to just that server:


"mcp_headers": {
  "X-Request-Id": "req_1",          // every server
  "integrations": { "X-Scope": "calendar" }   // only the "integrations" server
}

Your character’s stored integration credentials are applied after these, so a caller cannot substitute its own token for the one your workspace connected.

The embedded widget can set the same headers from the page, which is how a logged-in visitor’s tools act as that visitor:


window.__OsharaVoiceWidget.setMcpHeaders({
  Authorization: `Bearer ${shortLivedUserToken}`,
});
 
// or derive them from the metadata you already set:
window.__OsharaVoiceWidget.setMetadata({ user_id: "u_123", plan: "pro" });
window.__OsharaVoiceWidget.setForwardMetadataToMcp(true);
// -> X-Oshara-Meta-user_id: u_123, X-Oshara-Meta-plan: pro

See Context & Metadata for the full widget API.

Headers set from a page are visitor-visible and visitor-editable. Send short-lived, user-scoped tokens your MCP server validates itself, and don’t authorise an action on an X-Oshara-Meta-* value alone. For headers the agent must trust, mint the session from your backend instead.

Building an MCP server

An MCP server exposes a single HTTP endpoint that accepts a JSON body with:


{
  "tool": "tool_name",
  "arguments": { ... }
}

And returns:


{
  "result": { ... }
}

For the full MCP specification see modelcontextprotocol.io .