API Transports
API Transports expose AgentVisor™ agents to external clients through protocol-specific endpoints on a shared HTTP server.
This page covers the inbound direction. For the outbound direction — how agents access external services — see Gateways.
The Problem
AI agents must be accessible to diverse clients:
- AI assistants (Claude Desktop, Cursor) that discover and invoke tools
- Other AI agents that coordinate tasks across systems
- Web applications that orchestrate agent workflows
- Internal services that need programmatic agent access
Each client ecosystem has established protocols. Requiring clients to adopt a single protocol creates friction and limits adoption.
AgentVisor solves this by supporting multiple API transports - each speaking the native protocol of its target ecosystem while sharing common infrastructure.
Available Transports
| Transport | Protocol | Endpoint | Use Case |
|---|---|---|---|
| OpenAPI/REST | HTTP | / | LangGraph Agent Protocol clients, web applications, programmatic access |
| MCP | JSON-RPC 2.0 | /mcp | Claude Desktop, Cursor, MCP-compatible AI tools |
| A2A | JSON-RPC 2.0 | /a2a | Google Agent-to-Agent Protocol clients, multi-agent systems |
OpenAPI/REST Transport (Default)
The OpenAPI/REST transport implements the LangGraph Agent Protocol, providing:
- Thread and run management (
/threads,/runs) - Synchronous and asynchronous execution modes
- State streaming via Server-Sent Events
- OpenAPI specification at
/openapi.json - Swagger UI at
/swagger-ui/
This is the primary transport for programmatic agent access.
MCP Transport
The MCP transport implements the Model Context Protocol, exposing AgentVisor as an MCP server. External clients (Claude Desktop, Cursor, IDEs, other agents) can both invoke actions (tools) and browse runtime state (resources).
Tools (tools/list, tools/call) — six categories, all enabled by default:
- agents — one auto-generated invocation tool per registered agent
- threads —
create_thread,get_thread,update_thread,delete_thread,search_threads,copy_thread - runs —
get_run,list_runs,cancel_run,wait_for_run - state —
get_thread_state,update_thread_state,get_thread_history - store —
store_put,store_get,store_delete,store_search - system —
health_check,list_agents
Resources (resources/list, resources/read) — runtime state browsable via agentvisor:// URIs covering threads, checkpoints, agent schemas, and store items.
Categories can be selectively disabled via api.mcp.tools.<category> in configuration. See MCP Transport Guide for configuration and client setup.
A2A Transport
The A2A transport implements Google's Agent2Agent Protocol, enabling:
- Agent capability discovery via Agent Cards
- Task-based agent invocation
- Inter-agent communication for multi-agent workflows
See A2A Transport Guide for configuration and protocol details.
Shared Infrastructure
All transports share common infrastructure, ensuring consistent behavior:
┌──────────────────────────────────────────────────────────────────────┐
│ External Clients │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ Web Apps │ │ Claude Desktop │ │ A2A Agents │ │
│ │ REST clients │ │ Cursor │ │ Other systems │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ REST/HTTP MCP (JSON-RPC) A2A (JSON-RPC) │
│ │ │ │ │
├───────────┼──────────────────────┼──────────────────────┼────────────┤
│ Shared HTTP Server (api.listen_addr) │
│ │ │ │ │
│ ┌────────▼────────┐ ┌────────▼────────┐ ┌────────▼────────┐ │
│ │ OpenAPI │ │ MCP │ │ A2A │ │
│ │ Transport │ │ Transport │ │ Transport │ │
│ │ /threads, /runs │ │ /mcp │ │ /a2a │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ └──────────────────────┴──────────────────────┘ │
│ │ │
│ ┌─────────────▼─────────────┐ │
│ │ Shared Components │ │
│ │ • Authentication │ │
│ │ • TLS │ │
│ │ • Thread/Run API │ │
│ │ • Policy enforcement │ │
│ └───────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
Authentication
All transports share authentication configuration:
api:
auth:
enabled: true
oidc_issuer: "https://auth.example.com"
oidc_audience: "agentvisor"
When authentication is enabled, all transports require valid bearer tokens. The same token works across all endpoints.
TLS
All transports share TLS configuration:
api:
tls:
enabled: true
cert_file: "/path/to/server.crt"
key_file: "/path/to/server.key"
A single certificate secures all transport endpoints.
Policy Enforcement
All transport requests flow through the policy engine:
Client Request → Transport → Policy Engine → Agent Execution
│
Evaluate principal,
agent, and action
│
ALLOW or DENY
Policy decisions apply uniformly regardless of which transport received the request.
Configuration
Each transport is toggled independently under api.<transport>.enabled — OpenAPI/REST defaults
on, MCP and A2A default off. All three share the same listen address, authentication, and TLS
configuration, so enabling an additional transport never requires a separate listener or
certificate.
See the Configuration Reference for the full field list and environment variables.
Transport Selection
Choose transports based on your client ecosystem:
| Client Type | Recommended Transport |
|---|---|
| Web applications | OpenAPI |
| LangGraph clients | OpenAPI |
| Claude Desktop | MCP |
| Cursor | MCP |
| MCP-compatible tools | MCP |
| A2A agents | A2A |
| Multi-agent orchestration | A2A |
| Custom integrations | OpenAPI |
Multiple transports can be enabled simultaneously. Each provides a different interface to the same agents and capabilities.
Related Documentation
- MCP Transport Guide - Detailed MCP transport setup
- A2A Transport Guide - Detailed A2A transport setup
- Gateways - How agents access external services (opposite direction)
- Configuration Reference - Complete configuration options
- Architecture - System architecture overview