---

name: agent-tools description: "Use when configuring LiteLLM for MCP tools, A2A agents, Claude Code/Cursor agent gateway traffic, MCP auth/OAuth, tool permissions, semantic filtering, or agent-specific proxy routes." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Agent Tools

Use this sub-skill for LiteLLM workflows that expose tools or agents through the proxy. Route generic proxy setup to ../proxy-server/SKILL.md, provider endpoint details to ../providers-and-endpoints/SKILL.md, and SDK-only tools or tool_choice completion parameters to ../sdk-core/SKILL.md.

Choose the workflow

• MCP gateway for tools: configure mcp_servers, start the proxy, connect MCP-aware clients to /mcp or a scoped /mcp/{server} / /{server}/mcp endpoint, then validate tool discovery and auth headers with references/mcp-workflows.md.
• A2A agents: register or configure agents, discover them at /v1/agents, call JSON-RPC through /a2a/{agent_id}, or call a registered agent from LiteLLM routes with model name a2a/<agent-name>; see references/a2a-workflows.md.
• Claude Code and Cursor gateway traffic: make the client base URL point at the LiteLLM proxy endpoint that matches the client protocol, ensure requested model names match proxy model_name entries, and troubleshoot base URL/header confusion with references/agent-gateway-troubleshooting.md.
• Tool approval and policy: use proxy guardrails such as tool_permission, MCP server allowed_tools / disallowed_tools, key/team mcp_tool_permissions, and optional MCP semantic filtering before enabling broad tool access.
• Offline inspection: use scripts/inspect_mcp_tools.py to validate a JSON file containing OpenAI-format tool definitions or MCP server metadata without connecting to any external MCP server.

Minimal MCP gateway config

model_list:
  - model_name: claude-3-5-sonnet
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

mcp_servers:
  docs:
    url: https://example.invalid/mcp
    transport: http
    auth_type: authorization
    alias: docs

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Start the proxy with litellm --config config.yaml, then point an MCP client at http://localhost:4000/mcp with Authorization: Bearer <litellm-key> and x-mcp-servers: docs. For per-server upstream auth, prefer x-mcp-docs-authorization: Bearer <upstream-token> over a broad legacy x-mcp-auth header.

Minimal A2A agent config

agents:
  - agent_name: research-agent
    agent_card_params:
      name: Research Agent
      description: Answers research questions
      url: https://agent.example.invalid/
      version: "1.0.0"
      protocolVersion: "0.3.0"
      capabilities:
        streaming: true
      defaultInputModes: [text]
      defaultOutputModes: [text]
      skills:
        - id: research
          name: Research
          description: Research public information
          tags: [research]
    litellm_params: {}

Clients can discover with GET /v1/agents, send A2A JSON-RPC to /a2a/research-agent, or call LiteLLM chat/completion routes with model: a2a/research-agent when the agent is registered and the key/team is allowed to use it.

Validation checklist

• Confirm optional dependencies before using advanced flows: MCP needs the proxy MCP extra; direct A2A examples require a2a-sdk.
• Keep server identity consistent: server_name, alias, path-scoped MCP endpoint, x-mcp-servers, and x-mcp-<server>-authorization must refer to the same server label. Header matching is case-insensitive and checks alias before server name.
• Check auth precedence: server-specific MCP auth headers override legacy x-mcp-auth; OAuth per-user headers can override configured static tokens; config auth_value / authentication_token is used when no request header supplies auth.
• Verify agent permissions: non-admin keys can be denied for a2a/<agent-name> if key/team object permissions or access groups do not include the agent id.
• Inspect proxy logs for the exact model, MCP server, or agent name requested by Claude Code, Cursor, or an A2A client.

References

• references/mcp-workflows.md: MCP gateway setup, clients, auth, OAuth, permissions, semantic filtering, and offline inspection.
• references/a2a-workflows.md: A2A registration, discovery, direct JSON-RPC, LiteLLM a2a/ routing, and key/team permissions.
• references/agent-gateway-troubleshooting.md: Claude Code, Cursor, MCP/A2A failures, OAuth cache, semantic filters, and common access-denied paths.