Skip to main content

Model Context Protocol (MCP) Usage Guide

The Model Context Protocol (MCP) allows agents within the SVAHNAR framework to connect to external tool servers dynamically. This guide explains how to configure and use MCP servers with your agents.

Overview​

MCP is a standardized protocol that enables agents to discover and use tools hosted on remote or local servers. By acting as an MCP client, SVAHNAR agents can extend their capabilities without requiring custom code for every new tool integration.

Configuration​

To add an MCP server to an agent, use the mcp_assigned field within the tools section of your agent configuration YAML.

Configuration Fields​

  • name: A unique identifier for the MCP server connection.
  • hitl: (Boolean) If set to true, any tool call from this MCP server will require Human-In-The-Loop approval before execution.
  • config:
    • url: The endpoint URL of the MCP server (e.g., https://mcp.example.com/sse).
    • transport: The communication method. Defaults to streamable_http when omitted. streamable_http (also accepted as streamable-http or http) and sse are supported. sse is a legacy transport (superseded by streamable HTTP in the MCP spec); use it only for servers that don't yet support streamable HTTP.
    • headers: A dictionary of HTTP headers for authentication or metadata.
      • Authorization: Used for Bearer tokens or API keys (e.g., "Bearer xoxb-...").
      • Accept: Usually "text/event-stream, application/json" for MCP SSE connections.
    • oauth_provider_id: The UUID of your custom OAuth provider connection (see Custom OAuth Clients). When specified, SVAHNAR automatically fetches and silently refreshes the OAuth access token on behalf of the user, injecting it as an Authorization: Bearer <token> header.
  • assigned_tools: (Optional) A dictionary of specific tools to expose from this MCP server, along with default arguments to inject on every call. If omitted or empty, all tools are enabled with no default overrides. Default arguments can also use Key Vault placeholders (e.g., cc: ${MY_EMAIL}).

Example Agent Configuration​

create_agent_network:
  agent-1:
    agent_name: Agent_1
    agent_function:
      - >
        You are an agent which interact with arxiv to look for the research papers or articles 
        and later you can also connect with user provided mcp and perform task that user asks 
        for and answer him accordingly
    LLM_config:
      params:
        model: gpt-5  
    tools:
      tool_assigned:
        - name: Arxiv
          hitl: true
      mcp_assigned:
        # Option A: Authenticating using a Custom OAuth Connection (Recommended)
        - name: slack-mcp
          hitl: true
          assigned_tools:
            slack.post_message: 
              channel: "#general"   # Default argument injected automatically
          config:
            url: https://mcp.slack.com/mcp
            transport: streamable_http
            oauth_provider_id: "21af5063-05d2-4081-9e44-c3e2573b234f"
        # Option B: Authenticating using static headers with Key Vault secret placeholders
        - name: github-mcp
          hitl: false
          assigned_tools:
            github.create_issue: {} # Enable only this tool, no default args
          config:
            url: https://api.githubcopilot.com/mcp
            transport: streamable_http
            headers:
              Authorization: "Bearer ${GITHUB_PAT}"
    incoming_edge:
      - Start
    outgoing_edge: []

Adding an MCP Server from the UI​

You can also add and manage MCP servers without writing YAML. Open MCP Connections from the sidebar and click to add a new server.

1. Enter the server details​

Give the server a Name (e.g. math-service), an optional description, and the server URL (e.g. https://mcp.stripe.com).

2. Check sign-in​

Click Check Sign-in. SVAHNAR contacts the server and tells you whether it needs you to sign in:

  • No sign-in needed: you can go straight to fetching tools.
  • Sign-in required: SVAHNAR shows how it can connect. If you already have a saved connection for this server, a Link Connection button lets you reuse it (use Sign in if it needs to be re-authorized). You can also pick any saved connection from the dropdown.

3. Choose how SVAHNAR identifies itself (OAuth client)​

For servers that require sign-in, SVAHNAR lists only the options that server supports. When there is more than one, one is marked Recommended:

OptionWhat it does
Use SVAHNAR's published identityThe server reads SVAHNAR's client details from a URL we host. Nothing to set up.
Register automaticallySVAHNAR registers itself with the server when you connect. Nothing to set up.
Use your own OAuth clientEnter a Client ID (and Client Secret, if the server requires one) that you registered with the server yourself.

If you don't know where to get a Client ID or Secret, the form offers a ready-made search query you can Copy or open with Search Google.

Then click 1-Click Connect (or Save & Connect when using your own client) and approve access in the popup. If sign-in fails, use the Retry sign-in button after adjusting the settings. If something goes wrong during the popup flow you will land on an error page that explains what happened.

4. Review the permissions​

Under What this connection will ask for you can see the permissions (scopes) that will be requested, and where they came from (requested by the server, listed by the server, or offered by the sign-in server). If the server doesn't say which permissions it needs, none are requested and the sign-in server uses its default.

  • A warning appears if a permission the server asked for has been removed, since sign-in or tool calls will likely fail without it.
  • Anything SVAHNAR configures for you automatically is listed under Also set up for you.
  • Open Advanced: review or change these settings to switch individual extra settings on or off, tick or untick permissions, or add your own with Add another scope.
note

Some sign-ins don't include long-term access. SVAHNAR shows a notice with the expiry time, and you will need to sign in again after it.

5. Fetch tools and set per-tool permissions​

Click to fetch tools; SVAHNAR reports how many tools it found. For each tool you can:

  • Enable or disable it for agents.
  • Require Human-in-the-Loop approval before it runs.
  • Add the extra permissions that tool needs (for example channels:read). Type the scope and click + Add, or remove it with ×. Tools without extra needs show No extra permissions needed for this tool.

If a tool needs a permission your connection hasn't been granted yet, you'll be prompted to sign in to the connection again to grant it.

6. Use the server in an agent​

After saving, the Use this server in an agent panel offers:

  • Link to this saved server (Recommended): the agent references the saved server, so later changes apply automatically.
  • Copy the full settings: copies the complete YAML config into your agent.

In the agent network editor, MCP servers attached to an agent can also be configured directly on the agent node, including OAuth sign-in and tool permissions.

Security & Performance​

Disabled Transports​

For security reasons, the stdio transport is intentionally disabled for user-provided MCP configurations. All connections must be made via streamable HTTP (recommended) or legacy SSE.

Retries and Timeouts​

  • Timeout: Each connection attempt to an MCP server has a 10-second timeout to prevent the agent from hanging if a server is unresponsive.
  • Retries: The system will automatically attempt to reconnect up to 3 times if a transient error occurs during tool discovery.

Authentication Support​

SVAHNAR supports several options to securely authenticate with remote MCP servers:

By providing an oauth_provider_id in the config, SVAHNAR automatically manages the full OAuth 2.0 lifecycle on behalf of the user—including secure token storage and background silent refresh. The retrieved access token is dynamically injected into the MCP server requests as an Authorization: Bearer <token> header. See the Custom OAuth Clients Guide for detailed setup.

2. Static Headers with Key Vault Placeholders​

You can also supply static authentication tokens or API keys directly in the headers dictionary. To keep secrets secure and avoid hardcoding credentials in your YAML files, you can reference variables saved in your SVAHNAR Key Vault using the ${VARIABLE_NAME} syntax:

headers:
  Authorization: "Bearer ${MY_API_TOKEN}"

SVAHNAR will decrypt and substitute the placeholder values securely at runtime.

3. Other Header-Based Methods​

  • API Keys: Can be passed via custom headers (e.g. x-api-key: ${API_KEY}).
  • Basic Auth: Supported via the Authorization header with Base64 encoded credentials.