MCP tools

Reference

Greenlight exposes its functionality to coding agents as a fixed catalog of MCP tools. This page is the canonical reference: every tool, what it takes, what it returns, and a small example.

The conceptual model is in The agent protocol. This page assumes you know what MCP is and how an agent calls a tool.

Conventions

• Tool names are namespaced under greenlight.*. The dotted segments group related tools.
• Authorization is bound to the user the agent session is authenticated as. The agent cannot do anything the user couldn’t.
• Environment — Each app has one environment. Tools that accept env default to shared when omitted.
• Infra mutation (resource.add / remove, env.set / remove) updates server-side desired state in the control plane, runs the reconciler synchronously, and returns { plan, executed_ops, status } plus tool-specific fields. Resource and env configuration is governed at MCP call time; OPA gates deploy at merge.
• Errors follow the error envelope. code is stable; messages are not.
• Idempotency is supported on mutating tools that accept an idempotency_key. Repeated calls with the same key return the original response.
• Pagination is cursor-based; see Errors & pagination.

App lifecycle

greenlight.registerApp

Registers a new app. Creates the SCM repository, seeds greenlight.yml (identity + docs), branch protection, a shared environment row, and a default web workload row. Postgres and blob storage are provisioned separately via greenlight.resource.add when the app needs them.

Input

{
  "name": "expense-tracker",
  "slug": "expense-tracker",
  "type": "server",
  "description": "Quick reimbursement tracker for the finance team.",
  "idempotency_key": "uuid-v4"
}

Output

{
  "app_id": "app_k9x2m3p",
  "slug": "expense-tracker",
  "repo_full_name": "contoso/gl-expense-tracker",
  "clone_url": "https://github.com/contoso/gl-expense-tracker",
  "registration_state": "complete",
  "resumed": false
}

greenlight.resource.add

Provisions a managed resource in the app’s shared environment (Postgres logical database or blob container).

Input

{
  "app_id": "app_k9x2m3p",
  "env": "shared",
  "kind": "postgres",
  "options": {
    "postgres": { "extensions": ["uuid-ossp"] }
  }
}

Output (postgres)

{
  "plan": "provision postgres logical database for shared environment",
  "executed_ops": [{ "op": "create_logical_db", "status": "ok" }],
  "status": "complete",
  "resource_id": "res_pg_8s2",
  "type": "postgres",
  "env_var": "DATABASE_URL",
  "db_name": "gl_app_expense_tracker_shared"
}

greenlight.resource.remove

Removes a resource from the shared environment. Destructive; requires a reason and is audit-logged.

greenlight.listResources

Lists resources for an app. env defaults to shared.

Context (Knowledge)

greenlight.knowledge.list

Lists entry summaries for a scope.

Input

{
  "scope": "org" | "integration" | "app",
  "integration": "snowflake",
  "app_id": "app_k9x2m3p",
  "tags": ["data-modeling"],
  "cursor": "..."
}

Output

{
  "items": [
    { "id": "kn_pf2", "scope": "app", "topic": "architecture", "title": "App architecture", "version": 4, "updated_at": "2026-03-12T14:08:11Z" }
  ],
  "next_cursor": null
}

greenlight.knowledge.get

Returns one entry’s full body.

Input

{ "id": "kn_pf2" }

or

{ "scope": "app", "app_id": "app_k9x2m3p", "topic": "architecture" }

Output

{
  "id": "kn_pf2",
  "scope": "app",
  "topic": "architecture",
  "title": "App architecture",
  "body_md": "## Overview\n\nThis app...",
  "version": 4,
  "updated_at": "2026-03-12T14:08:11Z",
  "last_editor_kind": "agent"
}

greenlight.knowledge.search

Full-text search over titles and bodies.

Input

{ "query": "snowflake warehouse", "scope": "integration" }

Output

{
  "items": [
    { "id": "kn_a1", "title": "Snowflake warehouses we use", "scope": "integration", "snippet": "...the `ANALYTICS_PROD` warehouse..." }
  ],
  "next_cursor": null
}

greenlight.knowledge.propose

The agent write path. Always writes to knowledge_proposals; never mutates entries directly.

Input

{
  "scope": "app",
  "app_id": "app_k9x2m3p",
  "topic": "architecture",
  "title": "App architecture",
  "body_md": "...",
  "rationale": "Discovered a clean way to split the cron job from the API.",
  "base_version": 3
}

Output

{
  "proposal_id": "kp_xyz",
  "status": "pending"
}

Policy

greenlight.getPolicies

Returns the active policy bundle for the org. Agents call this before generating code to know the rules.

Input

{ "kind": "approved-base-images" }

kind is optional; omit to get the full bundle.

Output

{
  "policies": [
    { "id": "approved-base-images", "kind": "deny_if", "version": 12, "body": { "match": { /* … */ } } }
  ]
}

Integrations

greenlight.requestPermissions

Asks IT to grant one or more integrations to the calling app. Grants are app-scoped (not per-environment). Returns granted or pending per integration.

Input

{
  "app_id": "app_k9x2m3p",
  "requests": [
    { "integration": "snowflake-prod", "scope": "read", "reason": "Read the sales mart for the dashboard." }
  ]
}

Output

{
  "results": [
    { "integration": "snowflake-prod", "status": "granted" }
  ]
}

greenlight.getPermissions

Lists integration grants for the app.

Environment variables

greenlight.env.list / set / remove / pull

Manage env vars on the app’s shared environment. Values live in Key Vault at apps/<app-id>/env/shared/<name>; Postgres stores metadata only.

• set / remove — return { plan, executed_ops, status } (Key Vault write, secret render, optional rolling restart). sensitive: true routes the value to Key Vault; reserved system names are rejected.
• pull — Returns structured .env.local contents and short-lived local credentials. The agent writes the file; the MCP server does not touch the laptop filesystem. Returns fixture guidance when org policy disables local live data.

await greenlight.env.set({
  app_id: 'app_k9x2m3p',
  name: 'APPROVAL_SECRET',
  value: '…',
  env: 'shared',
  sensitive: true,
});

See App environment variables for reserved names and org policy fields.

Pipeline & operations

greenlight.createPullRequest / mergePullRequest

Open and merge pull requests on the app’s repo. Merge is gated by branch protection (greenlight/scanners and greenlight/policy must be green).

greenlight.getPipelineStatus / getPipelineFailure

Poll pipeline and policy-check state; getPipelineFailure returns structured remediation detail for the agent.

greenlight.getLogs / getMetrics / curlApp

Runtime observability and smoke checks against the deployed shared environment.

greenlight.getApp / listApps

Read app posture, shared environment metadata, resources, workloads, and grants.

Tip

Tool versioning is additive. Greenlight does not break the signature of an existing tool; new fields are optional and new tools are namespaced. Agents that work today keep working on future releases.

Note

Additional tools on the roadmap include workload mutation, public webhook routes, environment copy, and separate dev, prod, and preview environments. Today each app has one environment and a default web server created at registration.

Next

REST API The same surfaces, exposed to non-agent callers.

greenlight.yml Identity and docs metadata committed in each app repo.

Errors & pagination The error envelope and cursor scheme used everywhere.