MCP Servers

MCP Servers connect an agent to external systems through the Model Context Protocol.

In plain language: MCP gives the agent a structured way to use external tools from systems that already expose an MCP server.

What MCP Servers Are For

Use MCP when you want the agent to work with external tools or services such as:

• GitHub
• Slack
• Notion
• web search through Brave Search or Tavily
• databases
• custom services

What The MCP Page Supports

The page lets you:

• view configured servers
• browse a catalog of available integrations
• create a custom server
• connect supported services through OAuth
• enable or disable servers
• control which tools are enabled per server

Catalog vs Custom Server

Catalog vs Custom vs Tools

Use the catalog when the integration already exists and you want the fastest supported setup.

Brave Search and Tavily Search require your own provider API key. Web Fetch and Context7 remain available without an API key for reading public pages and library documentation.

Use a custom MCP server when your team already has a private MCP endpoint or needs a broader custom integration.

Use Tools instead when one direct HTTP action is enough and you do not need a larger MCP tool surface.

Runtime Data Visibility

Widget and public Chat API callers use the same three runtime field names:

Do not place secrets in context; it is model-visible and provider-visible during widget voice. MCP connections can use toolContext and toolCredentials only through stored binding and authentication configuration. Neither hidden field becomes a model-generated MCP argument.

Good Setup Flow

1. browse the catalog first
2. connect with OAuth when supported
3. enable only the tools the agent truly needs
4. test behavior in a safe environment
5. review conversation transcripts to confirm the agent uses the integration well

Widget Tool-Context Bindings

An embedded widget can provide non-secret toolContext values to an MCP server only through explicit connection bindings. Each binding maps one dot-separated context path to a non-sensitive request header:

{
  "connectionConfig": {
    "transport": "streamable-http",
    "url": "https://mcp.example.com/mcp",
    "toolContextBindings": [
      { "source": "toolContext", "path": "accountId", "target": { "type": "header", "name": "x-account-id" } }
    ]
  }
}

Authentication headers are reserved for the MCP auth configuration. Header names containing auth, token, secret, credential, password, or api-key are rejected as context targets. toolContext is not added to the model prompt or model-generated MCP arguments, and bound values are redacted if an MCP result echoes them, including inside JSON-encoded result text.

Widget Session Authentication

For a browser-held credential, provide a named SDK slot and reference that slot from the MCP server configuration:

createChatWidget({
  apiKey: 'spk_...',
  toolCredentials: { account: 'browser-token' },
})

{
  "authConfig": {
    "type": "widget-session",
    "slot": "account",
    "scheme": "bearer"
  }
}

Use scheme: "api-key" with an optional headerName, or scheme: "custom-header" with a required headerName, when the MCP endpoint does not use bearer authentication. The credential is read from the current widget request, stays in browser/widget memory, is never model input or conversation data, and is not persisted by the MCP server configuration. Missing slots fail before an outbound request.

For widget-session auth, text turns discover tools using the current request's credential. Persisted discovery from another user or a previous authentication mode is not reused. Enabled-tool and execution-policy filters still apply.

MCP Tools In Widget Voice

Native voice uses configured backend MCP tools under the agent's existing permissions and execution policies. The ElevenLabs browser-mediated relay is retired. It no longer sends discovery manifests or tool results to a remote agent. Browser-held widget-session credentials are not forwarded through that path.

Text and dashboard discovery/execution, including OAuth and configured server credentials, are unchanged. A required missing session credential produces SESSION_CREDENTIAL_REQUIRED, not anonymous discovery. Credentials, request headers and hidden runtime bindings must not be copied into speech prompts. Ending voice does not undo an external side effect already accepted by an MCP server.

Copilot Credential Handoffs

When Copilot creates an MCP integration that needs credentials or OAuth, it first saves an inactive agent-owned config. Credential fields then go directly to a secure server form, or the existing MCP OAuth route, instead of through the conversation. The action result contains only the handoff reference and status.

Completing credentials or OAuth does not activate the integration. Test the current config in a separately confirmed step, then confirm activation. Custom HTTP tools use a different contract: their environment secretRef is reference-only and must be provisioned outside Kravos.

Best Practices

• avoid exposing too many tools to one agent at once
• give each agent only the integrations that match its job
• validate permissions and expected outputs before launch
• compare MCP-based workflows with custom Tools if you are unsure which abstraction fits best

Setup Checklist

1. decide whether catalog, custom MCP, or a normal tool is the right fit
2. connect with OAuth or configure the custom endpoint
3. enable only the tools the agent actually needs
4. test the integration in a safe environment
5. review real transcripts to confirm the agent is using the integration correctly

Related Docs