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

> Learn to set up and configure MCP servers with authentication in Neuro-San Studio. Map server URLs, HTTP headers, and tool filters using a HOCON file and environment variables.

- Repository: [Cognizant AI Lab/neuro-san-studio](https://github.com/cognizant-ai-lab/neuro-san-studio)
- Tags: how-to-guide
- Published: 2026-02-27

---

**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:

```hocon
{
    "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:

```bash
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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/run.py)). Set it to the absolute path of your HOCON file:

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

```

When the CLI invokes [`run.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/servers/mcp/bmi_server.py).

A minimal server implementation:

```python
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:

```bash
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:

```hocon

# - 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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/run.py) can load it at startup.
- **Start MCP servers** using the `FastMCP` class pattern shown in [`servers/mcp/bmi_server.py`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/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`](https://github.com/cognizant-ai-lab/neuro-san-studio/blob/main/coded_tools/agent_network_editor/get_mcp_tool.py) before the tools are injected into the agent network.