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., http://127.0.0.1:8007/mcp).
    • transport: The communication method. Currently, http, sse, and streamable_http are supported (all map to HTTP-based communication).
    • 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.

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
          config:
            url: https://mcp.slack.com/mcp
            transport: sse
            oauth_provider_id: "21af5063-05d2-4081-9e44-c3e2573b234f"
        # Option B: Authenticating using static headers with Keyvault secret placeholders
        - name: github-mcp
          hitl: false
          config:
            url: https://api.githubcopilot.com/mcp
            transport: sse
            headers:
              Authorization: "Bearer ${GITHUB_PAT}"
    incoming_edge:
      - Start
    outgoing_edge: []

Security & Performance​

Disabled Transports​

For security reasons, the stdio transport is intentionally disabled for user-provided MCP configurations. All connections must be made via HTTP/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 Keyvault 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 Keyvault 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.