Protocol Coverage
Heartbit implements three protocols for tool connectivity, agent interoperability, and secure delegation.
Overview
Section titled “Overview”| Protocol | Version | Coverage |
|---|---|---|
| MCP (Model Context Protocol) | 2025-11-25 | Tools only (tools/list + tools/call over Streamable HTTP and stdio) |
| A2A (Agent-to-Agent) | 0.2.x | Agent card + 8-state task lifecycle |
| RFC 8693 | stable | Token exchange for MCP on-behalf-of |
MCP (Model Context Protocol)
Section titled “MCP (Model Context Protocol)”Heartbit includes an MCP client that connects to external tool servers. The protocol version is 2025-11-25.
Supported Operations
Section titled “Supported Operations”| Operation | Description |
|---|---|
tools/list | Discover available tools from an MCP server |
tools/call | Execute a tool on an MCP server |
Transport
Section titled “Transport”Two transports are supported:
- Streamable HTTP — Connect to MCP servers over HTTP (the primary transport)
- stdio — Connect to MCP servers via standard input/output (for local processes)
Configuration
Section titled “Configuration”MCP servers are configured per-agent in TOML:
[[agents]]name = "researcher"mcp_servers = ["http://localhost:8000/mcp"]
# With authentication# mcp_servers = [{ url = "http://localhost:8000/mcp", auth_header = "Bearer tok_xxx" }]Or via environment variable:
export HEARTBIT_MCP_SERVERS="http://localhost:8000/mcp,http://localhost:8001/mcp"Heartbit implements tools-only MCP. Resources, prompts, and other MCP capabilities are not currently supported. The client sends clientInfo.version matching the crate version.
A2A (Agent-to-Agent Protocol)
Section titled “A2A (Agent-to-Agent Protocol)”Heartbit supports the A2A protocol version 0.2.x for inter-agent communication. Requires the a2a feature flag.
Agent Card
Section titled “Agent Card”The daemon exposes an A2A agent card at /.well-known/agent.json describing the agent’s capabilities, supported content types, and task lifecycle.
Task Lifecycle
Section titled “Task Lifecycle”A2A tasks follow an 8-state lifecycle:
| State | Description |
|---|---|
submitted | Task received and queued |
working | Agent is actively processing (serde alias: working) |
input-required | Agent needs additional input from the caller |
auth-required | Authentication or authorization needed |
completed | Task finished successfully |
failed | Task failed with an error |
canceled | Task was canceled (serde alias: canceled) |
rejected | Task was rejected by the agent |
Configuration
Section titled “Configuration”A2A agents are configured via environment variable:
export HEARTBIT_A2A_AGENTS="http://agent1.example.com,http://agent2.example.com"RFC 8693 (Token Exchange)
Section titled “RFC 8693 (Token Exchange)”Heartbit implements RFC 8693 OAuth 2.0 Token Exchange for secure delegation when MCP servers need to act on behalf of the authenticated user.
How It Works
Section titled “How It Works”- The daemon receives a request authenticated with a JWT (via
[daemon.auth]JWKS configuration) - When calling an MCP server that requires user context, Heartbit exchanges the original token for a new scoped token
- The exchanged token is passed to the MCP server via the authentication header
- The MCP server can verify the token and act on behalf of the original user
Use Case
Section titled “Use Case”This enables multi-tenant scenarios where:
- Users authenticate to the Heartbit daemon via JWT
- MCP tool servers need to know which user is making the request
- Token exchange provides scoped, auditable delegation without sharing the original credential
The token exchange follows the standard RFC 8693 flow with urn:ietf:params:oauth:grant-type:token-exchange grant type.