Orbit MCP & A2A

MCP health, debug session intelligence, and A2A trust workflows for VS Code. Monitor companion services, inspect Agent Cards, and expose bounded tools to agent mode without leaving the editor.

Orbit MCP & A2A is the VS Code extension repository for developers operating MCP and A2A companion services. This repository owns the VS Code extension surface: editor views, native MCP discovery, configuration, SecretStorage, Workspace Trust enforcement, validation, redaction, diagnostics, and local audit output.

Orbit does not start or bundle its companion services. Runtime health data, debug-session history, and A2A registry state remain the responsibility of the separately operated health-monitor-mcp, debug-recorder-mcp, and a2a-warp services.

This repository contains:

• the released oaslananka.orbit-vsx VS Code extension;
• React webviews for MCP health, debug sessions, and A2A agent discovery;
• native MCP provider and Language Model Tool integrations;
• Agent Card validation, JWS trust verification, and safe public discovery;
• CI, coverage, workflow-security, provenance, and release automation.

What Orbit provides

Installation

Install Orbit from either extension registry:

• Visual Studio Marketplace
• Open VSX Registry

A signed release package is also available from GitHub Releases. To install a downloaded package from the command line:

code --install-extension .\orbit-vsx-0.6.1.vsix

The extension identifier is oaslananka.orbit-vsx.

Quick start

1. Install Orbit from the Visual Studio Marketplace, Open VSX, or a release .vsix.
2. Start only the companion services needed by your workflow:
   • health-monitor-mcp for Health Monitor and MCP Explorer;
   • debug-recorder-mcp for Debug Recorder;
   • a2a-warp and its registry server for A2A Explorer.
3. Open Preferences -> Settings -> Orbit and configure the endpoints and CLI path for your environment.
4. Store bearer tokens with Orbit: Health: Set Health Token and Orbit: Debug: Set Debug Token. Tokens are stored in VS Code SecretStorage, not workspace settings.
5. Open the Orbit Activity Bar container and refresh the enabled views.

If a panel reports a connection error or remains empty, verify that its companion service is running and reachable from the VS Code extension host.

Companion services and defaults

Panels can be enabled or disabled independently from Orbit settings.

Feature details

Health Monitor

Health Monitor displays server state, latency, uptime, recent checks, and pipeline summaries returned by health-monitor-mcp. From the tree view you can register, remove, inspect, and check MCP servers.

MCP Explorer

MCP Explorer presents the same health dashboard as a connection-focused tree. Orbit also contributes configured Health and Debug Recorder endpoints through VS Code's native MCP server definition provider API.

Debug Recorder

Debug Recorder creates and searches sessions through debug-recorder-mcp. It can record terminal commands and context, keep active/recent sessions bounded, and optionally mirror VS Code debug-session lifecycle events. Editor decoration hints and session tracking can be enabled or disabled without reloading VS Code.

A2A Explorer

A2A Explorer discovers registry agents, inspects Agent Cards, scans local agent-card.json files, validates cards on save, and scaffolds agents with the configured a2a-warp CLI.

Schema validity and cryptographic trust are deliberately separate. Trust states are:

• unsigned
• unverified
• verified
• invalid
• key-unavailable

Orbit supports bounded ES256 and RS256 JWS verification against same-origin or explicitly trusted public HTTPS JWKS endpoints. See the security model for the exact policy and limitations.

Agent Mode tools

Orbit contributes these read-only VS Code Language Model Tools:

• orbit_get_mcp_health
• orbit_list_mcp_servers
• orbit_search_debug_sessions
• orbit_get_debug_session_context
• orbit_list_a2a_agents
• orbit_validate_agent_card

The tools return bounded JSON text, redact URLs, honor cancellation, require Workspace Trust where necessary, and record security-relevant invocations in the Orbit:Audit output channel.

Configuration

Open Preferences -> Settings -> Orbit to view all settings. Common first-run settings and commands are:

Example workspace settings:

{
  "orbit.health.endpoint": "http://127.0.0.1:3000",
  "orbit.debug.endpoint": "http://127.0.0.1:3001",
  "orbit.a2a.registryUrl": "http://127.0.0.1:3099",
  "orbit.a2a.cliPath": "a2a-warp"
}

Use user or workspace settings only for non-secret values. Do not put bearer tokens in shared workspace files; use Orbit's SecretStorage commands.

Commands and usage

Open the Orbit Activity Bar view after configuring the companion services. View title buttons, item context menus, editor context menus, and the Command Palette provide the main actions.

Common operations include:

• refresh Health Monitor, Debug Recorder, A2A Explorer, and MCP Explorer;
• add, remove, inspect, and check MCP servers;
• create, close, search, and annotate debug sessions;
• discover agents, validate an agent-card.json, scaffold an agent, and open Agent Cards;
• set or clear Health and Debug bearer tokens securely.

Security and trust

Orbit treats companion services, workspace files, local CLIs, webviews, public URLs, JWKS documents, and discovered Agent Cards as separate trust boundaries. The extension applies Workspace Trust gates, SecretStorage migration, bounded network reads, DNS and redirect validation, strict webview CSP, typed audit records, and redacted error output.

Read:

• Security model
• Security policy
• Security tooling
• Repository governance

Release VSIX files, checksums, and SPDX SBOMs are published with GitHub artifact attestations. Verification instructions are documented in docs/RELEASE_GOVERNANCE.md.

Troubleshooting

A panel shows "Connection error"

Confirm the matching companion service is running and reachable from VS Code. Health Monitor and MCP Explorer use orbit.health.endpoint; Debug Recorder uses orbit.debug.endpoint; A2A Explorer uses orbit.a2a.registryUrl.

Requests return unauthorized responses

Set or replace the matching token through the Orbit Command Palette commands. Clear the token when the service does not require authentication. Legacy plaintext settings are migrated to SecretStorage and cleared from configuration scopes.

An endpoint is wrong or times out

Use the complete base URL, including protocol and port, such as http://127.0.0.1:3000. For containers and remote environments, expose or forward the port so it is reachable from the extension host.

A view is empty

An empty view usually means the service is reachable but has no records yet. Register an MCP server, start a debug session, or add agents to the A2A registry. Also verify that the view's *.enabled setting remains enabled.

A2A validation or scaffolding cannot find the CLI

Install a2a-warp or set orbit.a2a.cliPath to its absolute path. Refresh A2A Explorer after changing the path.

Development and verification

Orbit uses pnpm through the package-manager version declared in package.json. Install dependencies and run the repository verification chain:

corepack enable
corepack pnpm install --frozen-lockfile
corepack pnpm run verify

For Linux/headless environments:

corepack pnpm run verify:headless

The VS Code extension-host version can be pinned explicitly:

ORBIT_VSCODE_TEST_VERSION=1.100.0 corepack pnpm test
ORBIT_VSCODE_TEST_VERSION=stable corepack pnpm test

CI tests the minimum supported VS Code baseline with Node 22 and current stable VS Code with Node 24. Coverage, JUnit Test Analytics, production bundle size, CodeQL, Semgrep, dependency review, workflow security, and a clean headless container are also verified on pull requests.

Maintainer resources

• Changelog
• Maintainer roadmap
• Dependency policy
• Repository governance
• Release governance
• Observability and privacy
• Headless testing
• Codecov integration

Contributing

Read CONTRIBUTING.md for development setup, verification commands, and pull request expectations. Questions and support requests can be opened in GitHub Discussions.

License

Orbit MCP & A2A is available under the Apache License 2.0.