vscode-a2a

An MCP bridge that exposes A2A agents as tools in VS Code agent chat (GitHub Copilot, etc.).

Reads an a2a.json config, discovers each agent's card via .well-known/agent-card.json, and registers one MCP tool per agent. The LLM picks which agent to delegate to — multi-turn conversation is maintained automatically.

Compatible with A2A protocolVersion 0.3.0 and 1.0, JSONRPC and REST transports, and SSE streaming.

Installation

Via npx (recommended — works in VS Code, Cursor, Windsurf, Claude Desktop)

Add to your .vscode/mcp.json:

{
  "servers": {
    "vscode-a2a": {
      "command": "npx",
      "args": ["-y", "vscode-a2a"],
      "type": "stdio",
      "env": {
        "MY_AGENT_TOKEN": "${input:myAgentToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "myAgentToken",
      "type": "promptString",
      "description": "Bearer token for your A2A agents",
      "password": true
    }
  ]
}

From source

git clone https://github.com/kranthikirang/vscode-a2a
cd vscode-a2a && npm install && npm run build

Then point mcp.json at the built output:

"vscode-a2a": {
  "command": "node",
  "args": ["/path/to/vscode-a2a/dist/index.js"],
  "type": "stdio"
}

Configuration — a2a.json

Place .vscode/a2a.json (or a2a.json at project root) alongside your mcp.json. The bridge hot-reloads on save.

{
  "agents": {
    "my-agent": {
      "url": "https://example.com/my-agent/",
      // optional: override card discovery path or provide full card URL
      "cardPath": ".well-known/agent-card.json"
    }
  }
}

Agent card discovery

If cardPath is omitted the bridge tries in order:

1. {url}/.well-known/agent-card.json
2. {url}/.well-known/agent.json

If neither is reachable the agent is skipped (logged to stderr) and the bridge continues.

Authentication

All secret values support ${env:VAR_NAME} substitution — the variable is read from the process env injected by mcp.json.

az_cli — delegated user identity (recommended for developers)

No secrets required. Uses the user's existing az login session. The token carries the user's actual roles and groups, refreshes automatically.

// Shortest form — az_cli is the implicit default when no auth is specified
{
  "agents": {
    "my-agent": {
      "url": "https://my-gateway.example.com/agw/my-agent/",
      "resource": "api://your-azure-ad-app-client-id"
    }
  }
}

// Explicit form — same result, useful when mixing auth types across agents
"auth": {
  "type": "az_cli",
  "resource": "api://your-azure-ad-app-client-id"
}

resource is the Azure AD application (client) ID prefixed with api://. When omitted, the bridge attempts to discover it from the agent card's securitySchemes.

Prerequisite: az login must have been run at least once. VS Code terminals inherit this session automatically.

Bearer token

"auth": {
  "type": "bearer",
  "token": "${env:MY_AGENT_TOKEN}"
}

Pass the token via mcp.json env:

// .vscode/mcp.json
"env": { "MY_AGENT_TOKEN": "${input:myAgentToken}" }

API key

"auth": {
  "type": "apikey",
  "key": "${env:MY_API_KEY}",
  "header": "X-API-Key"   // optional, default: X-API-Key
}

OAuth2 client credentials (M2M / service principal)

"auth": {
  "type": "oauth2",
  "clientId": "your-client-id",
  "clientSecret": "${env:MY_CLIENT_SECRET}",
  "tokenUrl": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "scopes": ["api://your-app-id/.default"]
}

Tokens are cached and refreshed automatically 60 s before expiry.

Full example — multiple agents, different auth per agent

// .vscode/a2a.json
{
  "agents": {
    // az_cli shorthand — uses developer's `az login` session
    "prometheus-agent": {
      "url": "https://my-gateway.example.com/agw/prometheus-agent/",
      "resource": "api://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },

    // Same app registration, different agent — each gets its own resource
    "k8s-agent": {
      "url": "https://my-gateway.example.com/agw/k8s-agent/",
      "resource": "api://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },

    // Different app registration (different environment or org)
    "external-agent": {
      "url": "https://partner.example.com/agw/external/",
      "resource": "api://a1b2c3d4-0000-0000-0000-000000000000"
    },

    // M2M service principal (CI/CD, automation)
    "ci-agent": {
      "url": "https://my-gateway.example.com/agw/ci-agent/",
      "auth": {
        "type": "oauth2",
        "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "clientSecret": "${env:CI_CLIENT_SECRET}",
        "tokenUrl": "https://login.microsoftonline.com/tenant-id/oauth2/v2.0/token",
        "scopes": ["api://xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/.default"]
      }
    },

    // Static bearer token (non-Azure endpoints)
    "third-party-agent": {
      "url": "https://api.thirdparty.example.com/agent/",
      "auth": {
        "type": "bearer",
        "token": "${env:THIRD_PARTY_TOKEN}"
      }
    },

    // API key authentication
    "api-key-agent": {
      "url": "https://api.example.com/agent/",
      "auth": {
        "type": "apikey",
        "key": "${env:AGENT_API_KEY}",
        "header": "X-API-Key"
      }
    }
  }
}

How it works

a2a.json → discover .well-known/agent-card.json
         → register one MCP tool per agent (name + all skills in description)
         → LLM calls tool with { message, start_fresh? }
         → bridge sends A2A message/stream to agent
         → collects streamed artifacts → returns final text to LLM
         → preserves task ID for multi-turn (input-required state)

Multi-turn

The bridge keeps the same A2A contextId per agent for the lifetime of the MCP process. When an agent enters input-required state, the bridge returns the agent's question to the LLM; the next tool call continues the same task. Pass start_fresh: true to start a new context.

Live reload

Saving a2a.json triggers agent re-discovery and sends notifications/tools/list_changed to VS Code so new agents appear immediately without restarting.

Versioning

This package follows semver. To cut a release:

npm version patch   # 0.1.0 → 0.1.1  (bug fixes)
npm version minor   # 0.1.0 → 0.2.0  (new features, backwards-compatible)
npm version major   # 0.1.0 → 1.0.0  (breaking changes)
npm publish

npm version bumps package.json, commits, and creates a git tag automatically. prepublishOnly runs npm run build before every publish.

License

Apache-2.0