The agent protocol
Concept
Greenlight is agent-native. Coding agents register apps, read context, propose changes, inspect granted data, and call internal systems through a Model Context Protocol (MCP) interface, paired with a small set of universal Skills bundled in each agent plugin.
There is no human-language workaround. Anything an agent can do, it does through MCP directly or through the bundled greenlight command-line companion, which calls the same MCP tools with its own Greenlight credential. For running an app on a developer’s laptop, that companion also injects local runtime values without moving secrets through the agent.
MCP is the API
Section titled “MCP is the API”Greenlight exposes its functionality as a fixed catalog of MCP tools. Agents call them by name with structured arguments and get structured responses back. Authorization is bound to the user the agent session is attached to — the agent can never see or do anything that user couldn’t see or do.
The catalog spans these areas — a representative selection; the full inventory is authoritative:
| Area | Tools |
|---|---|
| App lifecycle | registerApp · getApp · listApps · getRepoAccess · addCoOwner · removeCoOwner |
| Delivery | createPullRequest · mergePullRequest · getPipelineRun |
| Environment variables | envList · envSet · envRemove |
| Context & policy | knowledgeList · knowledgeGet · knowledgeSearch · knowledgePropose · getPolicies |
| Integration grants | listGrantableIntegrations · requestCredentialAccess · getPermissions |
| Data inspection | inspectAppDb · inspectIntegrationApi · inspectAppBlob |
| Local development | approveCliSession |
| Observability | getLogs · getAppDiagnostics · curlApp · getAppPreviewUrl |
The full inventory, with inputs and outputs, lives in the MCP tools reference.
App infrastructure is declarative, not an MCP mutator. There are no resource.add or app-grant-request tools: the agent declares workloads, resources (Postgres, blob storage), and the app’s integration grants in greenlight.yml and opens a pull request. On merge, Greenlight provisions what’s declared and reconciles grants — auto-approving what policy allows and queuing the rest for IT review. registerApp itself creates only a scaffold (the app record and seeded repo); the first merged PR that declares infrastructure is what actually provisions it. The split: specs are declarative in the manifest, values are imperative — secrets and env values are set through envSet, never committed to the repo.
A person’s access is the one imperative request. A user has no manifest, so personal access — governed data for local work with no app, repo, or merge — is requested with requestCredentialAccess and reaches the same proxy under the user’s own identity. What an app can reach never depends on who invoked it; a person acts under their own explicitly granted authority. See Local development.
The flow after pushing a branch is createPullRequest → getPipelineRun(wait: true) — the pipeline tool long-polls until the run is terminal and carries per-check verdicts, structured failure detail, and the deployment URL, so the agent reads failures and fixes them from the same tool it waits on.
No credential ever reaches the agent
Section titled “No credential ever reaches the agent”A single rule shapes the whole protocol: a secret value never crosses the MCP boundary. No tool response contains an upstream credential, a connection string, or an environment-variable value. The agent works with names, identifiers, statuses, and results — never the keys behind them.
That’s why the agent never calls an external API directly. To use a data integration, the deployed app calls the Greenlight proxy and Greenlight swaps in the credential on the way out, or — for integrations IT chooses to inject — the credential is placed in the app’s environment at deploy time and the app calls upstream itself. Either way the agent only ever declares the grant in greenlight.yml and reads its status; it doesn’t handle the secret.
Developing locally against real data
Section titled “Developing locally against real data”An agent doesn’t have to deploy to see how its code behaves against real granted data. Two MCP-driven paths cover the local loop, and neither moves a credential onto the laptop:
- Inspect, to design and debug. The
inspectAppDb,inspectIntegrationApi, andinspectAppBlobtools run inside Greenlight and return only results — see the MCP tools reference. - Run, to exercise the app end-to-end. The bundled
greenlightCLI runs the app against the same governed values it gets in the cluster.
The full local loop — pairing the CLI, greenlight run, the same public proxy URL with a short-lived minted token, fixture databases, and what’s live versus fixture-only — lives in Local development.
Skills are universal
Section titled “Skills are universal”Every Greenlight plugin ships with the same small Skills library. A core greenlight Skill carries the end-to-end workflow and points to focused Skills, such as connected-databases, only when the task needs them. Every file is identical across customer installs. Together they teach the agent two things:
- The Greenlight protocol — which MCP tools exist, what they take, how to chain them, how to recover from errors, and how to drive the local companion.
- Workflow patterns — the canonical sequences for registering an app, opening a pull request, reading Knowledge, requesting an integration, and inspecting a data source.
Skills do not contain customer-specific content. Everything specific to a particular organization — the design system, integration playbooks, app architecture — flows through Knowledge at runtime, not through baked-in plugin files.
This separation matters: a plugin update doesn’t depend on what any one customer has authored, and customer prose never gets shipped inside a binary plugin package. App and integration Knowledge may be empty; agents still check it when relevant and propose durable context only after learning something useful.
One plugin per agent
Section titled “One plugin per agent”Greenlight ships a separate plugin for each supported coding agent. They all expose the same MCP catalog and the same Skills bundle — only the packaging differs.
| Agent | Install method |
|---|---|
| Codex | Marketplace plugin |
| Claude Code | Marketplace plugin |
| Cursor | Marketplace plugin |
| Copilot | MCP server registration |
| Gemini | MCP server registration |
A plugin’s runtime configuration — the MCP endpoint URL, the plugin version, and a handful of org-specific facts the agent needs before its first MCP call — is delivered per organization through generated marketplace repositories. Public is the default so agents that clone the repo from GitHub (the Claude Code CLI, Codex, Cursor) work without every citizen developer having Git credentials; a private variant is what the Claude admin console’s Plugins tab accepts, serving an Anthropic-hosted copy to Claude.ai and Claude Desktop with no repository access needed. Every variant contains the same generated plugin artifacts and no secrets, private Knowledge, policy bundles, or implementation code. The plugin binary itself — including the bundled greenlight companion — stays universal.
For Claude Code, IT’s organization rollout also pre-approves the plugin’s Greenlight MCP server, Greenlight CLI operations, and installation or refresh from the trusted control-plane-hosted CLI routes. Auto Mode stays active for everything else; Greenlight’s own identity, RBAC, policy gate, and audit remain the boundary for Greenlight actions.
The agent’s scope is bounded
Section titled “The agent’s scope is bounded”A Greenlight agent session is authenticated as a specific user and inherits exactly that user’s RBAC. It cannot escalate. It cannot impersonate. It cannot see apps the bound user doesn’t have access to, propose changes to integrations the user doesn’t own, or call tools the user’s role doesn’t permit. The local companion inherits the same identity: pairing binds it to the agent’s MCP session, so revoking the user’s Greenlight session revokes the laptop’s access too.
If the agent runs into something its bound user can’t do, the only path forward is to ask the user to escalate — through the dashboard, the integration permission flow, or a conversation with IT. The agent doesn’t have a side door.