Azure MCP Agent Starter

天蓝色mcp制剂起始剂

  

用于构建连接到的Azure AI Foundry代理的入门套件 多个MCP服务器同时运行 --内置配置驱动的服务器注册、每服务器身份验证和只读安全强制。

克隆它，填写你的 .env，并在10分钟内运行一个工作的多服务器代理。

______________________________________________________________________

这个工具包能给你什么

______________________________________________________________________

建筑

flowchart LR
    U(["👤 User"]):::user -->|"chat query"| MAIN["main.py\nAgent Loop"]:::agent

    subgraph FOUNDRY ["Azure AI Foundry"]
        MAIN -->|"user prompt +\ntool definitions"| LLM["LLM\n(Responses API)"]:::llm
        LLM -->|"tool_calls[]"| MAIN
    end

    MAIN -->|"dispatch by\nfunction name"| TOOLS["tools.py\nTOOL_FUNCTIONS"]:::tools

    subgraph REGISTRY ["Server Registry"]
        direction TB
        TOOLS -->|"get_mcp_client(label)"| REG["ServerRegistry\nmcp_servers.yaml"]:::registry
        REG -->|"build provider"| AUTH["Auth Provider\n(API Key / PAT / OAuth)"]:::auth
    end

    subgraph MCP_SERVERS ["MCP Servers"]
        direction TB
        AUTH -->|"HTTP + headers"| HTTP_MCP["HTTP MCP Server\n(Azure Functions)"]:::mcp
        AUTH -->|"stdio + env vars"| STDIO_MCP["Stdio MCP Server\n(subprocess)"]:::mcp
    end

    HTTP_MCP -->|"JSON-RPC response"| NORM["Normalizer\n(standard envelope)"]:::norm
    STDIO_MCP -->|"JSON-RPC response"| NORM
    NORM -->|"normalized result"| MAIN
    MAIN -->|"answer +\ndeep links"| U

    classDef user fill:#E8F5E9,stroke:#388E3C,color:#1B5E20
    classDef agent fill:#E3F2FD,stroke:#1565C0,color:#0D47A1
    classDef llm fill:#FFF3E0,stroke:#EF6C00,color:#BF360C
    classDef tools fill:#F3E5F5,stroke:#7B1FA2,color:#4A148C
    classDef registry fill:#FFF9C4,stroke:#F9A825,color:#F57F17
    classDef auth fill:#FFECB3,stroke:#FFA000,color:#E65100
    classDef mcp fill:#E0F7FA,stroke:#00838F,color:#006064
    classDef norm fill:#FCE4EC,stroke:#C62828,color:#B71C1C

这 ServerRegistry 读取 mcp_servers.yaml 在启动时自动连接每个服务器的身份验证。通过添加YAML条目添加新服务器——不需要更改Python。

______________________________________________________________________

快速开始

详细信息请参见 QUICKSTART.md.

先决条件：

步骤：

# 1. Clone and install
git clone https://github.com/RajAnandakumar-Microsoft/azure-mcp-agent-starter.git
cd azure-mcp-agent-starter/agent_app
pip install -r requirements.txt

# 2. Configure
cp .env.example .env
# fill in AZURE_EXISTING_AIPROJECT_ENDPOINT and AZURE_EXISTING_AGENT_ID

# 3. Log in
az login

# 4. Start the demo MCP server (separate terminal)
cd ../demo_mcp_server
func start --port 7070

# 5. Run the agent
python -m agent_app.main

试着问：

• show me authentication requirements
• what's related to REQ-001?
• find architecture components tagged with "API Gateway"

______________________________________________________________________

添加自己的MCP服务器（4个步骤，无需代码）

正在寻找要连接的服务器？ 看 MCP_SERVERS_DIRECTORY.md 为了 25+官方Microsoft MCP服务器，以及Jama Connect、IcePanel和社区 服务器——每台都已准备就绪 mcp_servers.yaml 配置。

1. 向添加条目 mcp_servers.yaml:

servers:
  - label: my_system
    description: "My system"
    transport: http
    url: "${MY_SYSTEM_URL:-http://localhost:7071/api}"
    auth:
      type: api_key
      header: "x-functions-key"
      env_var: MY_SYSTEM_KEY
    read_only: true

2. 将变量添加到 .env:

MY_SYSTEM_KEY=your-key

3. 在中添加工具 agent_app/tools.py:

@ai_function
async def search_my_system(query: str) -> str:
    """Search my system for artifacts matching query."""
    client = get_mcp_client("my_system")
    return await client.call_tool("search", {"q": query})

4. 重新启动代理。新服务器已自动注册。

看 示例/README.md 用于身份验证配方、stdio服务器和响应规范化。

______________________________________________________________________

身份验证指南

入门套件支持 6种身份验证类型 开箱即用。每个MCP服务器在 mcp_servers.yaml，因此您可以自由地混合和匹配-一个服务器使用API密钥，另一个使用OAuth，第三个使用Azure Identity。

none --匿名/本地开发

auth:
  type: none

没有凭据。用于接受匿名访问的本地开发服务器或MCP服务器。

api_key --HTTP头注入

auth:
  type: api_key
  header: "x-functions-key"     # HTTP header name
  env_var: MY_FUNCTION_KEY      # Env var holding the key

在启动时从env-var读取密钥，并将其作为HTTP标头注入到每个请求中。典型的Azure函数。

pat --个人访问令牌

auth:
  type: pat
  env_var: ADO_MCP_AUTH_TOKEN          # Env var holding the PAT
  stdio_auth_flag: "--authentication"  # Optional: CLI flag for stdio servers
  stdio_auth_value: "envvar"           # Optional: value for the flag

• HTTP服务器： 发送为 Authorization: Bearer .
• stdio服务器： 将env-var以及可选的CLI标志注入到子流程环境中。

oauth --通过SOAP授权OAuth

# Confidential client (service-to-service, no user interaction)
auth:
  type: oauth
  tenant_id: "${AZURE_TENANT_ID}"
  client_id: "${GRAPH_CLIENT_ID}"
  scopes:
    - "https://graph.microsoft.com/.default"
  client_secret_env_var: GRAPH_CLIENT_SECRET

# Public client (interactive browser login — omit client_secret_env_var)
auth:
  type: oauth
  tenant_id: "${AZURE_TENANT_ID}"
  client_id: "${SP_CLIENT_ID}"
  scopes:
    - "https://graph.microsoft.com/Sites.Read.All"

用途 铝合金迷你气缸 用于代币收购。支持：

• 机密客户 （与 client_secret_env_var)：客户端凭据授予，无用户交互
• 公共客户端 （无秘密）：首次调用时交互式浏览器登录，然后静默令牌刷新

要求： pip install msal

azure_identity --DefaultAzureCredential

auth:
  type: azure_identity
  scopes:
    - "https://management.azure.com/.default"

用途 DefaultAzureCredential 来自Azure身份SDK。这就是 Azure本机服务的推荐身份验证类型 因为：

• 适用于 az login 本地
• 在部署的环境中使用托管身份
• 自动处理令牌刷新
• 不需要客户机密或PAT

要求： pip install azure-identity （已在requirements.txt中）

启动验证

呼叫 validate_credentials() 启动时检查所有服务器是否具有有效的身份验证配置：

from agent_app.registry.server_registry import init_registry

registry = init_registry("mcp_servers.yaml")
issues = registry.validate_credentials()
for label, problems in issues.items():
    for p in problems:
        print(f"⚠️  Server '{label}': {p}")

添加自定义身份验证类型

1. 在中创建新的提供程序类 agent_app/auth/ 实施 get_headers(), get_env_vars(), get_stdio_args()，以及 validate()
2. 在中添加案例 agent_app/auth/factory.py
3. 出口自 agent_app/auth/__init__.py
4. 在中添加测试 agent_app/tests/test_auth_providers.py

______________________________________________________________________

存储库布局

azure-mcp-agent-starter/
├── .github/
│   └── copilot-instructions.md    # Copilot rules (single source of truth)
├── agent_app/                      # Main agent application
│   ├── auth/                       # AuthProvider protocol + 6 implementations
│   ├── registry/                   # Config-driven ServerRegistry
│   ├── normalization/              # Response envelope normalizer
│   ├── tests/                      # 100+ unit tests
│   ├── config.py                   # Environment loading & typed config
│   ├── main.py                     # Agent run loop (entry point)
│   ├── tools.py                    # Agent tool definitions
│   ├── mcp_client.py               # JSON-RPC 2.0 HTTP + stdio clients
│   └── mcp_utils.py                # Parallel MCP fetch utilities
├── demo_mcp_server/                # Azure Functions demo MCP server
│   ├── function_app.py             # MCP endpoint (JAMA + IcePanel demo data)
│   ├── demo_data.py                # Demo fixtures
│   └── mcp_response.py             # Standard response envelope helper
├── tests/                          # Integration tests (MCP protocol + endpoint)
├── examples/                       # Guides for extending the kit
│   ├── README.md                   # Extension guide
│   ├── auth_patterns.md            # Auth recipe examples
│   └── custom_http_server/README.md
├── mcp_servers.yaml                # Server registry (edit to add/remove servers)
├── MCP_SERVERS_DIRECTORY.md        # Catalog of available MCP servers to plug in
├── .env.example                    # Environment variable template
├── QUICKSTART.md                   # 10-minute setup guide
├── ruff.toml                       # Linter / formatter config
└── README.md                       # This file

______________________________________________________________________

运行测试

pytest agent_app/tests/ -v

pytest tests/ -v          # MCP protocol + endpoint integration tests

______________________________________________________________________

关键设计决策

______________________________________________________________________

贡献

看 贡献.md.

许可证

麻省理工学院