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 · knowledgeAssetList · knowledgeAssetGet · knowledgePropose · getPolicies |
| Integration grants | listGrantableIntegrations · requestCredentialAccess · getPermissions Coming soon |
| Local development | approveCliSession · inspectAppDb · inspectAppBlob · inspectIntegrationApi · inspectIntegrationDb |
| 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,inspectAppBlob,inspectIntegrationApi, andinspectIntegrationDbtools 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, storage and user-passthrough, 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 package, several clients
Section titled “One plugin package, several clients”Greenlight ships one plugin package. Its portable core — Agent Skills and Streamable HTTP MCP — conforms to Agent Plugins 1.0. Client-specific adapters (Claude Code, Codex, Cursor) ride alongside that core. Installation, org policy, identity, and authorization stay client-specific and Greenlight-governed. The package is not certified, and it does not claim to work with every agent.
They all expose the same MCP catalog and the same Skills bundle — only the client adapter differs.
| Agent | Install method |
|---|---|
| Codex | Marketplace plugin |
| Claude Code | Marketplace plugin |
| Cursor | Team marketplace plugin |
| Copilot | Marketplace plugin |
| 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. The create form starts on a private repository. The organization rollouts — Claude’s Organization settings → Plugins & skills, the OpenAI admin console’s marketplace import, and a Cursor team marketplace served from Cursor — work from a private repository because the vendor reads it once through an admin’s connection and serves its own copy, with no repository access needed on any desktop. Claude’s organization plugin also reaches Claude Code signed in with claude.ai. Copilot, Claude Code without a claude.ai sign-in, and every self-serve install clone the repository from GitHub, so those need a public one or Git credentials, and the form tells you so. 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.
IT’s organization rollout also removes the approval click. The recommended setting keeps each agent’s own review in place and pre-approves Greenlight: Claude Code’s Auto Mode with the Greenlight policy, Codex’s automatic reviewer with the Greenlight policy, Cursor’s Auto-review with the Greenlight entries, and Copilot’s managed allow rules for the greenlight command and your Greenlight host. An organization that would rather its agent never asked can choose the agent’s no-prompts mode instead; Agent setup names it for each agent. Either way, Greenlight’s own identity, RBAC, policy gate, and audit remain the boundary for Greenlight actions.
More detail: calls that can still ask
- A Cursor call that is not on the allowlist goes to Auto-review, which can still ask. Enterprise sets the allowlist in the dashboard; Teams members set it in the app.
- On Codex, the automatic reviewer approves Greenlight’s commands and still reviews everything else.
- Downloading or refreshing the command-line program from the Greenlight site can still ask on Cursor. Claude’s, Codex’s and Copilot’s policies cover that path.
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 whoever approves its code — the agent over its MCP session with approveCliSession, or an authenticated POST /api/cli/approve when MCP is unavailable — so revoking that 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.