FoundryIQ stdio MCP Server

Exposes the FoundryIQ (Azure AI Search) RFP knowledge base as a native MCP tool (knowledge_base_retrieve) over stdio, so an MCP client (VS Code, GitHub Copilot CLI, etc.) can call it directly instead of shelling out to a script per question.

A fresh Azure AD access token (scoped to search.azure.com) is minted on every tool call via the Azure CLI (az account get-access-token) — nothing is hardcoded and the token never goes stale.

Prerequisites

• Python 3.10+ (this project was verified with Python 3.13)
• Azure CLI installed and logged in:

  az login
  

  You must have access to the tenant/subscription that hosts the FoundryIQ search service referenced in config.json (the server requests a token for that specific tenant, so it works even if it differs from your CLI's active tenant/subscription).

Setup

1. Create and activate a virtual environment (already present as .venv/ in this repo — recreate it if missing):

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Copy config.example.json to config.json and fill in your knowledge base settings:

   Copy-Item config.example.json config.json
   

   {
     "endpoint": "https://<your-search-service>.search.windows.net",
     "kb_name": "<your-knowledge-base-name>",
     "api_version": "2026-05-01-preview",
     "token_resource": "https://search.azure.com",
     "tenant_id": "<tenant-guid>",
     "subscription_id": "<subscription-guid>"
   }
   

   tenant_id / subscription_id are optional but recommended when the knowledge base lives in a different tenant/subscription than your CLI's default login context. config.json is gitignored — it holds your real values and should never be committed.

Running standalone (sanity check)

The server speaks MCP JSON-RPC over stdio, so running it directly will just block waiting for input on stdin — that's expected:

.\.venv\Scripts\python.exe foundryiq_mcp_server.py --config config.json

Press Ctrl+C to stop. This is only useful to confirm the process starts without import/config errors; normally an MCP client launches and drives it.

Registering with an MCP client

VS Code (mcp.json)

Add an entry to your workspace or user mcp.json (Command Palette → "MCP: Open User Configuration", or a .vscode/mcp.json in this repo):

{
  "servers": {
    "foundryiq": {
      "type": "stdio",
      "command": "c:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\.venv\\Scripts\\python.exe",
      "args": [
        "c:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\foundryiq_mcp_server.py",
        "--config",
        "c:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\config.json"
      ]
    }
  }
}

GitHub Copilot CLI (and Microsoft Scout, which rides on it)

The Copilot CLI reads its MCP server registrations from ~/.copilot/mcp-config.json (i.e. C:\Users\<you>\.copilot\mcp-config.json on Windows). Add/update the foundryiq entry there:

{
  "mcpServers": {
    "foundryiq": {
      "type": "local",
      "command": "C:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\foundryiq_mcp_server.py",
        "--config",
        "C:\\Users\\sansri\\stdio-mcpservers\\foundryiq-rfp-kb\\config.json"
      ],
      "tools": ["knowledge_base_retrieve"]
    }
  }
}

Note the schema differs slightly from VS Code's mcp.json: Copilot CLI uses "mcpServers" (not "servers") and "type": "local" (not "stdio"), but the underlying mechanism is identical — a local subprocess over stdin/stdout, no URL/port involved. Microsoft Scout calls into the same Copilot CLI MCP config, so registering it here also makes knowledge_base_retrieve callable from Scout. Restart Scout / start a new Copilot CLI session after editing this file for the change to take effect.

Microsoft Scout "Add MCP Server" dialog (GUI alternative)

Scout also has a GUI front-end for the same mcp-config.json — if you'd rather not hand-edit the file, use its Add MCP Server dialog instead (check first whether foundryiq already shows up in Scout's server list from the file edit above; if so, skip this to avoid a duplicate registration):

• Name: foundryiq-rfp-kb
• Remote/Local: Command
• Command (paste as one combined string):

  C:\Users\sansri\stdio-mcpservers\foundryiq-rfp-kb\.venv\Scripts\python.exe C:\Users\sansri\stdio-mcpservers\foundryiq-rfp-kb\foundryiq_mcp_server.py --config C:\Users\sansri\stdio-mcpservers\foundryiq-rfp-kb\config.json
  

• Environment variables: leave blank (auth comes from your existing az login session, not env vars)
• Tool-call timeout: the default (~60s) is usually fine, but consider ~90s for headroom — the retrieval pipeline does query planning + parallel search + semantic rerank plus a fresh token mint on every call.

Other MCP clients

Point the client's server registration at the same venv Python + script + --config path shown above. Use absolute paths so the server resolves correctly regardless of the client's working directory.

Microsoft Scout skill (SKILL.md)

This repo also includes SKILL.md — a Scout skill that teaches the agent how to use the registered foundryiq-rfp-kb-knowledge_base_retrieve MCP tool correctly (call it directly instead of shelling out, treat the returned chunks as the only source of truth, always append a citation-naming instruction to the query, never decompose the user's request into sub-questions, etc.).

Registering the MCP server (steps above) is not enough on its own — Scout needs this skill imported separately so the agent knows these usage rules exist and when to invoke the tool. Two things have to both be true for Scout to use this correctly:

1. The foundryiq MCP server is registered in ~/.copilot/mcp-config.json (see the GitHub Copilot CLI section above) — this is what makes the foundryiq-rfp-kb-knowledge_base_retrieve tool exist at all.
2. SKILL.md is imported into Scout's Skills/Extensions. In Scout, add this skill via its extensions/skills UI (import from this repo path) so the skill's name/description frontmatter is indexed and Scout knows to route FoundryIQ/knowledge-base questions through this tool with the correct calling convention.

After importing, restart Scout (or start a new session) so it re-discovers both the MCP tool and the skill.

Config resolution order

--config flag → FOUNDRYIQ_CONFIG env var → config.json in the process's current working directory. Individual FOUNDRYIQ_* env vars (FOUNDRYIQ_ENDPOINT, FOUNDRYIQ_KB_NAME, FOUNDRYIQ_API_VERSION, FOUNDRYIQ_TOKEN_RESOURCE, FOUNDRYIQ_TENANT_ID, FOUNDRYIQ_SUBSCRIPTION_ID) override individual fields on top of whatever config file was loaded.

Exposed tool

• knowledge_base_retrieve(queries: list[str]) -> str — runs the knowledge base's agentic retrieval pipeline and returns the retrieved grounding chunks as Markdown (### Reference N blocks with ref_id + content). It returns source chunks only; the caller/model synthesizes the final answer from them.

Troubleshooting

• Failed to acquire Azure Search token. Run 'az login' first. — your CLI session expired or doesn't have access to the tenant/subscription in config.json. Re-run az login (and az login --tenant <tenant_id> if needed).
• No config found — ensure config.json exists next to the script, or pass --config <path> / set FOUNDRYIQ_CONFIG.
• Stray output breaking the client — all logging must go to stderr (this is already handled in foundryiq_mcp_server.py); don't add print() calls that write to stdout.