How to Set Up and Configure MCP Servers with Authentication in Neuro-San Studio

Configure MCP servers by creating a HOCON file that maps server URLs to HTTP headers and tool filters, then expose that file path via the MCP_SERVERS_INFO_FILE environment variable before launching Neuro-San Studio.

Model Context Protocol (MCP) servers expose tool interfaces that agents call through a uniform HTTP-based protocol. Neuro-San Studio discovers and authenticates those servers by reading a HOCON configuration file whose path is supplied via the MCP_SERVERS_INFO_FILE environment variable. This guide walks through the exact steps to set up and configure MCP servers with authentication based on the source code in cognizant-ai-lab/neuro-san-studio.

Configure the MCP Server List in HOCON

Create or edit a HOCON file that maps each server URL to optional HTTP headers and an optional tool filter. The repository ships an example at mcp/mcp_info.hocon.

The file structure follows this pattern:

{
    "https://mcp.deepwiki.com/mcp": {
        "tools": ["read_wiki_structure", "ask_question"]
    },

    # Uncomment to use the GitHub Copilot MCP server.

    # "https://api.githubcopilot.com/mcp": {

    #     "http_headers": {

    #         "Authorization": "Bearer ${GITHUB_TOKEN}"

    #     },

    #     "tools": ["issue_write"]

    # },

    # Uncomment to use the Google Maps Grounding-Lite MCP server.

    # "https://mapstools.googleapis.com/mcp": {

    #     "http_headers": {

    #         "X-Goog-Api-Key": ${GOOGLE_API_KEY}

    #     },

    #     "tools": ["search_places", "lookup_weather", "compute_routes"]

    # }

}

Key configuration fields:

• http_headers – Key/value pairs sent with every request to the server. Values can reference environment variables using ${VAR_NAME} syntax, resolved at runtime.
• tools – Optional whitelist; if omitted, the client receives all tools offered by the server.

Provide Authentication Secrets via Environment Variables

Export the environment variables referenced in the HOCON file before launching Neuro-San Studio. For the examples above:

export GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXX"
export GOOGLE_API_KEY="AIzaSyXXXXXXXXXXXXXXXXXXXX"

Security best practices: Keep these secrets out of source control. The repository includes an .env.example file showing expected variable names without values. Load them via a .env file or your deployment platform's secret management system.

Point the Runtime to the Configuration File

Neuro-San Studio reads the MCP_SERVERS_INFO_FILE variable at startup (handled in run.py). Set it to the absolute path of your HOCON file:

export MCP_SERVERS_INFO_FILE="$(pwd)/mcp/mcp_info.hocon"

When the CLI invokes run.py, the runner prints the value (around line 192) so you can verify it was picked up.

Start the MCP Server

Each server is a regular Python service built on the FastMCP class. See the example server at servers/mcp/bmi_server.py.

A minimal server implementation:

from mcp.server.fastmcp import FastMCP

# Create a BMI-calculating MCP server listening on port 8000

mcp = FastMCP("BMI", port=8000)

# Register a tool

mcp.register_tool("calculate_bmi", lambda height, weight: weight / (height/100)**2)

# Run the server – blocks until the process is stopped

mcp.run()

Run it with:

python -m servers.mcp.bmi_server

The server logs its URL (e.g., http://localhost:8000/mcp). Add that URL to mcp_info.hocon if you want agents to call it.

Consume MCP Tools in Agent Networks

Agent network HOCON files reference MCP tools in the tools block. The manifest at registries/tools/manifest.hocon contains a comment pointing to the authentication file:

# - Use MCP_SERVERS_INFO_FILE for authentication.

#   See https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/mcp/mcp_info.hocon 

#   and https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/docs/user_guide.md#authentication

When an agent network loads, the get_mcp_tool helper in coded_tools/agent_network_editor/get_mcp_tool.py reads MCP_SERVERS_INFO_FILE, builds a dictionary of {url: tool_list}, and injects those URLs into the agent's tools list. If the HOCON entry includes http_headers, they attach automatically to every outbound request, satisfying the server's authentication requirements.

Verify Your Configuration

Check these items to confirm your setup works:

• Environment variable set – echo $MCP_SERVERS_INFO_FILE should print the absolute path to your HOCON file.
• Server reachability – curl -I http://localhost:8000/mcp should return 200 OK.
• Agent discovery – Start Neuro-San Studio (python run.py …) and look for log lines listing MCP tools (e.g., "Discovered MCP tool http://localhost:8000/mcp – tools: [calculate_bmi]").

If authentication fails, the server returns 401 Unauthorized. Verify that the header key/value in mcp_info.hocon matches the server's expectation and that the secret environment variable is exported in the same shell where Neuro-San Studio runs.

Summary

• Create a HOCON configuration at mcp/mcp_info.hocon mapping server URLs to http_headers and optional tools filters.
• Export secrets as environment variables referenced by ${VAR_NAME} syntax in the HOCON file.
• Set MCP_SERVERS_INFO_FILE to the absolute path of your HOCON file so run.py can load it at startup.
• Start MCP servers using the FastMCP class pattern shown in servers/mcp/bmi_server.py.
• Verify via environment checks, curl tests, and Neuro-San Studio logs that tools are discovered and authenticated correctly.

Frequently Asked Questions

What file format does Neuro-San Studio use for MCP server configuration?

Neuro-San Studio uses HOCON (Human-Optimized Config Object Notation) for MCP server configuration. The file typically resides at mcp/mcp_info.hocon and supports environment variable substitution using ${VAR_NAME} syntax, comments, and nested objects for headers and tool filtering.

How does authentication work for external MCP servers like GitHub Copilot or Google Maps?

Authentication works via the http_headers field in the HOCON configuration. You define header key-value pairs where values reference environment variables (e.g., "Authorization": "Bearer ${GITHUB_TOKEN}"). When Neuro-San Studio initializes, the get_mcp_tool.py helper resolves these variables and attaches the headers to every outbound request to that MCP server.

Can I restrict which tools from an MCP server are available to agents?

Yes. Use the optional tools array in the HOCON configuration to whitelist specific tools. If you omit the tools field, Neuro-San Studio imports all tools exposed by that MCP server. This filtering happens during the discovery phase in coded_tools/agent_network_editor/get_mcp_tool.py before the tools are injected into the agent network.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}