MCP Servers
Canopy ships two distinct MCP (Model Context Protocol) servers - one for Host, one for Cortex - each with its own tool set. There is also a third, unrelated concept (“hosted MCP servers”) that reuses the “MCP” name but is a marketplace feature, not a server you connect an MCP client to. This page covers all three, kept clearly separate.
Host’s MCP server
Section titled “Host’s MCP server”Package canopy-host-mcp (host/mcp/), built on mcp.server.fastmcp.FastMCP.
Exposes read/write tools over the Canopy Host API for coding agents and
MCP clients (Claude Desktop, Claude Code, etc.).
Connecting
Section titled “Connecting”- Transport:
stdioby default (CANOPY_HOST_MCP_TRANSPORT), or streamable-http/SSE. CANOPY_HOST_API_URL(defaulthttps://api.canopy.pm) +CANOPY_HOST_API_KEY- the server calls the Host API on your behalf using this key.- Alternatively, connect with OAuth 2.1: Canopy self-hosts an
authorization server at
auth.canopy.pm(Ory Hydra). A client that supports OAuth/DCR (Claude Code, Claude.ai, ChatGPT, Codex) discovers it automatically and authorizes through your Canopy account - no API key to copy around. Either way you end up with a bearer token scoped to your own account; there’s no third, separate MCP-level credential. - Public URL:
https://mcp.canopy.pm, health check athttps://mcp.canopy.pm/mcp/health(always reachable, reportshost_mcp_hosting_feature_enabled,tool_count, and the live tool list).
Example stdio client config:
{ "mcpServers": { "canopy-host": { "command": "canopy-host-mcp", "env": { "CANOPY_HOST_API_KEY": "your-api-key" } } }}Feature-gated: the whole tool set is gated behind the
host.mcp.hosting platform feature. If it resolves disabled, zero tools
are registered (the server stays up, tools/list is just empty) - see
Platform Features.
The server registers a default core set; CANOPY_HOST_MCP_TOOL_PROFILE adds opt-in groups (ci, compute,
pipelines, graph, governance, library, source, staff) or all. A profile controls which tools are listed,
never what you may do: the Host API still authorizes every call. The four host_source_* tools are in the source
profile and, like the Canopy Source routes behind them, need the host.source platform feature and
source:read.
| Tool | Params | What it does |
|---|---|---|
host_list_projects |
limit?, cursor? |
List projects, paginated (25/page by default) |
host_get_project |
project_id |
Look up one project |
host_get_environment |
environment_id |
Fetch an environment |
host_get_environment_variables |
environment_id |
List its variables (values masked - a value_preview only) |
host_reveal_environment_variable |
environment_id, name |
Real plaintext value of ONE named variable (requires confirmation in clients that support it) |
host_get_environment_domains |
environment_id, limit?, cursor? |
List its domains, cursor paginated |
host_get_environment_runtime_logs |
environment_id, lines?, process?, app_service_id?, previous? |
Snapshot of the app’s own stdout/stderr; previous reads the last crashed container |
host_create_environment |
project_id, branch?, repository?, build_path?, build_command?, build_type?, template_id?, name?, migrate_command?, image?, build_only?, package_build?, defer_first_build?, native_bundle_artifact_id?, grove_id?, config? |
Create an environment (image creates one from an OCI image and starts its first deploy; native_bundle_artifact_id with grove_id creates one from an uploaded native bundle on a native Grove) |
host_update_environment |
environment_id, source_scope?, build_path?, build_command?, build_type?, migrate_command?, health_mode?, backup_consistency?, predeploy_backup?, build_only?, package_build? |
Update build config, how the app is health-checked, how backups treat volumes, and whether a backup runs before an image change |
host_list_builds |
environment_id, page? |
List builds (page 1 by default) |
host_get_build |
environment_id, build_id |
Fetch one build |
host_trigger_deploy |
environment_id, no_cache?, no_reuse?, image? |
Trigger a deploy (image moves an image environment to a new reference) |
host_rollback |
environment_id, build_id |
Roll back to a build |
host_cancel_build |
environment_id, build_id |
Cancel a running build |
host_deploy_approval |
environment_id, build_id, action |
Approve/reject a gated deploy |
host_set_variables |
environment_id, variables, app_service_id? |
Bulk-set env vars (for one service when app_service_id is given) |
host_mark_variable_secret |
environment_id, name, app_service_id? |
Hide a variable’s value everywhere without changing it |
host_add_domain |
environment_id, domain, app_service_id? |
Add a custom domain (pointing at a web service when app_service_id is given); it gets no traffic until verified |
host_get_domain_dns |
environment_id, domain_id |
DNS records to create, the ownership TXT record and a live DNS check |
host_verify_domain |
environment_id, domain_id |
Prove ownership of a domain via its _canopy-challenge TXT record |
host_list_previews |
environment_id, include_destroyed? |
List a source environment’s PR preview environments (read-only) |
host_preview_settings |
environment_id, enabled?, ttl_hours?, max_concurrent?, fork_policy? |
Read an environment’s preview settings, or change only the ones given |
host_environment_protection |
environment_id, mode? |
Read who may reach an environment, or set it to public, authenticated or organization |
host_get_preview |
environment_id, preview_id |
One preview with its workload phase and databases (read-only) |
host_destroy_preview |
environment_id, preview_id |
Tear a preview down (destructive, idempotent) |
host_list_backups |
environment_id |
List an environment’s database backups (read-only) |
host_get_backup |
environment_id, backup_id |
One backup’s status and metadata (read-only) |
host_create_backup |
environment_id |
Take a manual backup (rate limited; restore is not a tool) |
host_get_restore_status |
environment_id, restore_id |
Status of a backup restore (read-only) |
host_get_environment_database |
environment_id |
The environment’s primary database, no connection details (read-only) |
host_list_environment_storage |
environment_id |
Persistent storage mounts (read-only) |
host_list_volumes |
environment_id |
Persistent volumes of a Forest environment: mount path, size, status, retention (read-only) |
host_create_volume |
environment_id, name, mount_path, size_gb?, process?, retention_days?, apply? |
Create a persistent volume; redeploys the current artifact once unless apply is false |
host_detach_volume |
environment_id, volume_id |
Detach a volume and keep its data for the retention period (permanent deletion is CLI-only) |
host_attach_volume |
environment_id, volume_id |
Mount a detached volume again |
host_list_adoptable_volumes |
environment_id |
Detached volumes of the project this environment can mount (read-only) |
host_adopt_volume |
environment_id, volume_id, mount_path, name?, process?, apply? |
Mount a detached volume with its data intact |
host_get_destroy_plan |
environment_id |
What deleting an environment would affect and the retain/delete choices (read-only; deleting is CLI-only) |
host_check_environment |
environment_id |
Check whether an environment can be deployed without deploying it: image, user, port, volumes, replicas, variables, domains, health (read-only) |
host_get_environment_state |
environment_id |
One page of health: rollout, restarts and why, volumes, routes, last backup, failing crons, problems (read-only) |
host_list_environment_jobs |
environment_id, kind?, limit? |
Scheduled commands with next run and recent runs, or recorded one-off and release-task runs (read-only) |
host_get_environment_config |
environment_id |
The .canopy.yml document the environment deploys with (read-only) |
host_get_config_file |
environment_id, kind, service_id?, include_content? |
Where a service’s .canopy.yml or canopy.pipeline.ts is in its repository and whether the connection may write it |
host_list_config_revisions |
environment_id |
Recorded configuration revisions, newest first (read-only) |
host_set_environment_config |
environment_id, content, apply? |
Record a new configuration revision and redeploy with it unless apply is false |
host_get_environment_language_settings |
environment_id, revision?, service_id? |
The languages detected in an environment’s source and the build settings they unlock (read-only) |
host_set_environment_language_settings |
environment_id, settings, service_id? |
Set language build settings (true/false, null resets); applies on the next build |
host_analyze_environment_languages |
environment_id, service_id? |
Queue a fresh language analysis of the current source revision |
host_list_app_services |
environment_id, kind? |
An environment’s services (web, worker or job), optionally of one kind (read-only) |
host_get_blueprint |
environment_id |
An environment’s Blueprint: nodes, links, runtime state, warnings (read-only) |
host_plan_blueprint |
environment_id, document?, patch?, revision? |
Plan a Blueprint change from a full document, a stored revision number or a list of edits. Changes nothing; returns the ordered operations (immediate or next deploy), impacts, errors with fixes, and a plan id. Needs project:blueprint |
host_setup_project |
team_id, setup |
Create a project (or add environments to one) with services, Blueprint, domains and first deploys as one durable operation |
host_get_setup |
team_id, setup_id? |
One setup with per-step status, or the team’s recent setups |
host_continue_setup |
team_id, setup_id, abandon? |
Run the steps of a failed setup that are not done, or give up and remove what it created |
host_resume_blueprint_apply |
environment_id, apply_id, acknowledge_impacts?, deploy? |
Finish the newest partially applied or failed apply by re-planning the same Blueprint and running what is left |
host_apply_blueprint |
environment_id, plan_id, acknowledge_impacts?, deploy? |
Apply a reviewed plan. The plan id is required, so review cannot be skipped. Does not deploy unless deploy is true; a plan with destructive impacts needs acknowledge_impacts. A partially applied or failed apply is a normal result |
host_list_blueprint_applies |
environment_id, apply_id?, limit?, before? |
An environment’s Blueprint applies, newest first, or one apply with per-operation results (read-only) |
host_get_blueprint_status |
project_id |
A project’s newest revision, your draft, and each environment’s adoption state, applied revision and last apply (read-only) |
host_adopt_blueprint |
project_id, environment_ids, confirm?, message? |
Derive the project Blueprint from same-shape environments: a draft to review, or with confirm revision 1 published and the environments adopted |
host_draft_blueprint_from_environment |
project_id, environment_id |
Replace your draft with what an environment is now, to keep changes made outside the Blueprint |
host_get_blueprint_drift |
environment_id |
Compare an environment with the revision it last applied (read-only) |
host_get_template_blueprint |
template_id |
A template read as a Blueprint, with its required variables and notes on what the mapping dropped (read-only) |
host_save_template_blueprint |
template_id, document |
Write a Blueprint document back to a template’s service rows; per-environment overrides, groups and external hosts are refused |
host_plan_template_blueprint |
environment_id, template_id |
Plan a template into an environment with its repositories attached; changes nothing until the plan is applied |
host_finish_template_blueprint |
environment_id, template_id, values? |
After the apply, add the template’s service variables, build steps and required variables; safe to repeat |
host_save_blueprint_as_template |
project_id, name, slug, description?, visibility?, revision? |
Create a template from a published Blueprint revision, every service kept |
host_propose_environment_services |
repository, branch, project_id?, team_id? |
Propose a repository’s services from its compose file or Dockerfiles; use team_id before any project exists (read-only) |
host_propose_blueprint |
repository, branch, project_id?, team_id?, provider? |
Propose a Blueprint from a repository’s root: the document, the evidence behind each node and link, what was left out, and the planner’s dry run. Creates nothing; needs environment:create and the host.blueprint feature (read-only) |
host_list_blueprint_revisions |
project_id, revision?, limit?, cursor? |
A project’s Blueprint revisions, newest first, or one revision with its document (read-only) |
host_diff_blueprint_revisions |
project_id, from_revision, to_revision |
What changed between two revisions of a project’s Blueprint (read-only) |
host_get_blueprint_draft |
project_id |
Your draft of a project’s Blueprint: base and latest revision, whether it is stale, the document (read-only) |
host_save_blueprint_draft |
project_id, document, base_revision |
Replace your draft with a document edited from base_revision (null when the project has none); 409 if a newer revision exists; publishes nothing |
host_rebase_blueprint_draft |
project_id, choices? |
Move your draft onto the newest revision; conflicts come back with ids to settle |
host_publish_blueprint_draft |
project_id, message? |
Store your draft as the next revision and remove it; 409 if a newer revision exists; changes no environment |
host_discard_blueprint_draft |
project_id |
Remove your draft; published revisions are untouched |
host_revert_blueprint |
project_id, to_revision, base_revision?, message? |
Add a revision equal to an earlier one; history is kept and no environment changes |
host_apply_app_services |
environment_id, services |
Configure a new environment from reviewed services, all-or-nothing |
host_create_app_service |
environment_id, service |
Add a service (Forest only, needs the host.environment_services feature); service.source {repository_id} builds it from another attached repository |
host_update_app_service |
environment_id, service_id, changes |
Change a service’s settings; applies on the next build; changes.source {repository_id} moves it to another attached repository |
host_delete_app_service |
environment_id, service_id |
Remove a service (not default, not one with domains or volumes) |
host_get_app_service_state |
environment_id, service_id |
What one service is doing now, with the age of the Grove’s report (read-only) |
host_scale_app_service |
environment_id, service_id, replicas, process? |
Set the replicas of a service’s process; 0 pauses a worker |
host_service_grove_bindings |
environment_id, service_id, grove_bindings? |
Read the machines a service may ask Host for, or replace them (at most 8) |
host_restart_app_service |
environment_id, service_id |
Roll a service’s pods from the image they already run |
host_set_app_service_autoscale |
environment_id, service_id, process, min_replicas, max_replicas, target_cpu_percent |
Keep a process’s replicas in a range, steered by CPU |
host_run_command |
environment_id, command, service_id?, process?, with_volumes? |
Run a one-off command in the default service or in one service’s process |
host_run_app_service_job |
environment_id, service_id, command?, with_volumes? |
Run a job service once from its live release image |
host_get_app_service_execution_output |
environment_id, service_id, execution_id |
The end of what a finished job execution printed; needs deploy permission (read-only) |
host_list_app_service_executions |
environment_id, service_id |
A job service’s recent executions with status and exit code (read-only) |
host_list_environment_releases |
environment_id, limit?, before? |
An environment’s releases with each service’s image; active marks the live one (read-only) |
host_list_environment_repositories |
environment_id |
PREVIEW: the repositories an environment builds from, primary first (read-only; needs host.multi_repository) |
host_attach_environment_repository |
environment_id, repository, provider, branch? |
PREVIEW: attach a secondary repository and register its webhook (needs host.multi_repository and project:blueprint) |
host_detach_environment_repository |
environment_id, repository_id, force? |
PREVIEW: detach a secondary repository and its webhook; refused for the primary or while a service uses it |
host_list_clone_identities |
team_id |
PREVIEW: a team’s clone identities, with scope and expiry and never a secret (read-only; needs team:manage and host.multi_repository) |
host_rollback_to_release |
environment_id, release_id |
Roll back to a release that was live (creates a rollback build) |
host_list_team_roles |
team_id |
A team’s custom roles and their actions (read-only, preview API) |
host_get_team_role |
team_id, role_id |
One custom role (read-only) |
host_get_my_permissions |
team_id |
What you can do on the team, per product action: available, or the one thing in the way (read-only) |
host_list_alert_rules |
team_id |
A team’s alert rules, without webhook URLs (read-only) |
host_list_alert_events |
team_id |
A team’s recent alert events (read-only) |
host_list_team_images |
team_id, limit? |
Docker images a team pushed to the registry, with each tag’s digest-pinned ref (read-only) |
host_list_api_keys |
The caller’s API keys, never key material (read-only) | |
host_start_job |
team_id, purpose, image_ref, command, timeout_seconds?, memory_mb?, cpus?, egress? |
Start an ephemeral isolated job and return at once |
host_get_job |
job_id |
A job’s state, exit code and output once finished (read-only) |
host_list_jobs |
team_id, limit? |
A team’s recent jobs (read-only) |
host_get_job_events |
job_id, after? |
A job’s lifecycle events (read-only) |
host_cancel_job |
job_id |
Cancel a job that has not started running |
host_submit_compute_job |
team_id, steps, grove? |
Submit a compute job and return at once; poll host_get_compute_job. Steps run in order on a build Grove. Requires compute:submit; GPU use can be restricted by entitlement and budget |
host_get_compute_job |
job_id, artifacts? |
A compute job’s status and each step’s state, exit code, error and Grove; artifacts adds the output digests of succeeded steps (read-only) |
host_list_compute_jobs |
team_id, status?, limit?, cursor? |
A team’s compute jobs, newest first, paged with next_cursor (read-only) |
host_cancel_compute_job |
job_id |
Cancel a running compute job and ask its Grove to stop what it started |
host_deploy_and_wait |
environment_id, poll_interval_seconds?, poll_timeout_seconds? |
Deploy, then poll to terminal status |
host_artifact_lineage |
team_id, digest? or commit?, include_impact? |
Trace an artifact’s lineage |
host_artifact_passport |
artifact_id, sections? |
Fetch an artifact’s passport ({available: false} if not generated yet); optionally limit returned sections |
host_release_and_promote |
project_id, source_environment_id, target_environment_id, version, build_id?, notes?, poll_interval_seconds?, poll_timeout_seconds? |
Full release → promote → approve → poll chain |
host_catalog_search |
team_id, q?, limit?, cursor? |
Search the workflow marketplace |
host_catalog_install |
team_id, workflow_id, granted_permissions |
Install a workflow |
host_catalog_run |
team_id, installation_id |
Run an installed workflow |
host_environment_recommendations |
environment_id, limit?, cursor? |
Read-only rightsizing recommendations |
host_compliance_status |
team_id, limit?, cursor? |
List compliance evidence packages |
host_compliance_package |
team_id, package_id |
Fetch one package |
host_environment_residency |
environment_id |
Residency attestations for an environment |
host_artifact_residency |
artifact_id |
Residency attestations for an artifact |
host_list_ci_connections |
team_id, limit?, cursor? |
List Canopy Connect connections |
host_list_ci_pipelines |
connection_id, limit?, cursor? |
List pipelines for a connection |
host_list_ci_runs |
pipeline_id, limit?, cursor? |
List runs for a pipeline |
host_get_ci_run |
run_id |
Fetch a run + its jobs |
host_explain_ci_failure |
run_id |
Failed jobs only, with failure excerpts (deterministic, no model call) |
host_import_ci_connection |
connection_id |
Import an existing CI connection |
host_get_timeline |
environment_id, cursor?, limit? |
Unified build + CI-run timeline |
host_cost_summary |
team_id, since?, until? |
Cost summary |
host_cost_anomalies |
team_id, threshold_pct? |
Spend anomalies |
host_budgets |
team_id, limit?, cursor? |
List budgets |
host_pipeline_get_graph |
graph_id, detail? |
Fetch a pipeline graph |
host_pipeline_get_plan |
graph_id |
Fetch a pipeline’s execution plan |
host_pipeline_get_run_status |
graph_id |
Fetch a pipeline run’s status |
host_pipeline_diff_graphs |
graph_id, against_graph_id |
Diff two pipeline graphs |
host_pipeline_simulate |
environment_id, ref, commit, untrusted? |
Simulate a pipeline run without applying it |
host_pipeline_validate |
environment_id, ref?, commit?, content?, service_id?, untrusted? |
Would this pipeline plan? Pass content to check an unsaved edit (preview) |
host_pipeline_detect_dead_steps |
graph_id |
Find unreachable/dead steps |
host_pipeline_suggest_parallel |
graph_id |
Suggest steps safe to parallelize |
host_graph_node |
ref |
Fetch one engineering-graph node (preview) |
host_graph_edges |
ref, depth? |
Traverse graph edges (depth clamped 0-3) (preview) |
host_graph_commit |
sha |
Correlate a commit across the graph (preview) |
host_graph_kinds |
- | List engineering-graph node kinds (preview) |
host_graph_dependencies |
ref |
List a node’s dependencies (preview) |
host_graph_impact |
ref |
Blast-radius/impact analysis for a node (preview) |
host_graph_events |
ref, after_sequence?, page_size? |
Events associated with a node (preview) |
host_graph_release_live_at |
environment_id, at? |
What was live on an environment at a point in time (preview) |
host_source_repositories |
environment_id |
The repositories an environment builds from, the commits deployed and your provider access (preview, source profile) |
host_source_read |
environment_id, repository_id, path, at? |
A directory listing or a text file up to 32 KB at a revision; larger or non-text files say so instead of returning content (preview, source profile) |
host_source_log |
environment_id, repository_id, at?, path?, cursor? |
Commits newest first, 30 per page; continue with next_cursor and the returned sha (preview, source profile) |
host_source_compare |
environment_id, base, head?, repository_id?, path?, node? |
What changed between two snapshots (every repository), two revisions of one repository (files and commits), or one file’s patch with path; never whole patches (preview, source profile) |
host_space_search |
space_id, query, kinds? |
Search within a Space, Host-only (preview) |
host_deploy_space |
space_id |
Deploy a Space (preview) |
host_get_space_deploy |
space_id, space_deploy_id |
Fetch a Space deploy’s status (preview) |
host_list_teams |
- | List teams |
host_list_native_groves |
team_id |
A team’s native Groves (Macs) with state and auto_placement (read-only) |
host_update_native_grove |
team_id, grove_id, auto_placement?, pools?, portable_steps?, image_builds?, secrets_allowed? |
Opt a native Grove in or out of automatic placement, replace its pool labels, and set which work it accepts: container steps, image builds, steps with secrets (idempotent) |
host_pipeline_secrets |
team_id, action?, name?, value? |
A team’s pipeline secrets. action list (names only, the default), set (needs name and value) or remove (needs name). A value is never returned; changing needs variables:write |
host_promotion_policies |
team_id, policy_id? |
A team’s promotion policies, or one with its document (read-only) |
host_list_incidents |
environment_id, incident_id? |
An environment’s detected incidents, or one with its timeline (read-only) |
host_list_operations |
team_id, operation_id?, status?, environment_id?, limit?, cursor? |
A team’s operations timeline of builds, deploys and promotions, or one operation (read-only) |
host_list_notifications |
none | Your notifications, newest first (read-only) |
host_mark_notifications_read |
notification_id? |
Mark one notification read, or all when omitted |
host_diagnose_native_grove |
team_id, grove_id |
A redacted bundle for one native Grove: state, heartbeat and poll age, the last checks and active_jobs, the steps revoking it would fail (read-only) |
host_revoke_native_grove |
team_id, grove_id |
Revoke a native Grove: it stops taking work and its running steps fail (destructive; needs grove:manage) |
host_list_templates |
limit?, cursor? |
List templates |
host_get_account |
- | Current user |
host_get_plan |
- | Current billing plan |
host_list_system_information |
- | What needs your attention now: action items such as an expired git connection or an expiring clone identity, and announcements (read-only) |
host_audit_search |
team_id, event_type?, limit?, cursor? |
Search the audit event ledger |
host_list_webhooks |
environment_id |
List git provider webhooks for an environment’s repository |
host_create_webhook |
environment_id |
Register a webhook, if one isn’t already (idempotent) |
host_secure_webhook |
environment_id |
Generate/rotate the webhook signing secret |
host_delete_webhook |
environment_id, hook_id |
Delete one provider webhook by id (from host_list_webhooks) |
host_observability_status |
- | Unresolved findings from every platform detection sweep (staff-only, read-only) |
host_ops_status |
- | One-page platform health: dead-man report, invariant violations, build queue, Grove heartbeats, dead jobs (staff-only, read-only) |
host_list_groves |
- | List every enrolled Forest Grove (staff-only) |
host_grove_build_jobs |
grove_id, status?, build_id?, limit?, offset? |
A Grove’s build-dispatch jobs (staff-only) |
host_grove_workloads |
grove_id |
A Grove’s raw workloads rows, incl. sync_cursor (staff-only) |
host_list_execution_placements |
subject_kind, subject_id, node_id? |
Which Grove each node of a build, sandbox run or environment was placed on, and why (staff-only, at most 500 rows) |
host_get_accelerator_inventory |
substrate?, vendor?, include_empty? |
Each Grove’s accelerators with allocatable and free counts, its placement units and whether the report is stale, as placement sees them (staff-only; behind the execution observability feature) |
host_get_native_groves |
grove_id?, workload_limit? |
Native Groves: health, machine (sleep, AC power, disk), workloads with per-instance state, and active jobs (staff-only; behind the execution observability feature) |
host_list_grove_placements |
grove_id, subject_kind?, limit?, cursor? |
The placements recorded on one Grove, newest first, paged with next_cursor (staff-only; behind the execution observability feature) |
host_get_accelerator_entitlement |
team_id |
A team’s accelerator entitlement: override, plan columns and the effective value (staff-only) |
host_get_accelerator_usage |
team_id |
A team’s accelerator-seconds consumed this and last UTC month, with the remaining budget (staff-only) |
host_admin_set_accelerator_entitlement |
team_id, reason, max_accelerators_per_run?, seconds_budget?, budget_mode?, unlimited_budget?, clear_fields? |
Change a team’s accelerator entitlement override; audited, only the fields passed change (staff-only) |
host_list_artifact_blobs |
team_id, type? |
A team’s content-addressed artifact blobs (up to 50 per call) |
host_pipeline_graphs_reap |
build_id?, environment_id?, commit?, confirm? |
Delete stale pipeline_graphs row(s) by build, or by environment and commit (staff-only) |
host_admin_set_team_feature_opt_in |
feature_key, team_id, opted_in, reason |
Opt a team in to or out of a preview platform feature (staff-only) |
host_pipeline_images_audit |
images |
Is each pinned image digest reachable from the platform registry and every active build Grove’s own registry? (staff-only, read-only) |
Deliberately not exposed: reporting a CI run (that’s a CI
credential’s job via canopy ci report, not something an agent should
do on a user’s behalf) - see host_explain_ci_failure/host_get_ci_run
for the read-only equivalent.
Cortex’s MCP server
Section titled “Cortex’s MCP server”Package cortex-mcp (cortex/mcp/), a separate process with its own
tool set for Cortex’s knowledge/RAG/training/agent-run surfaces.
Connecting
Section titled “Connecting”- Transport:
stdio,streamable-http, orsse(CORTEX_MCP_TRANSPORT). - HTTP transports require authentication at startup. Choose one mode:
CORTEX_MCP_REQUIRE_BEARER_AUTH=truewithCORTEX_MCP_BEARER_TOKENfor a shared server secret, orCORTEX_MCP_MULTI_TENANT=trueso each caller’s own Cortex API key is forwarded and checked by Cortex. These modes are mutually exclusive. The shared-secret mode authenticates access to the MCP server; it does not give each caller a distinct Cortex identity. The multi-tenant mode does.stdiohas no HTTP authentication and is intended for a trusted local client. CORTEX_API_URL(defaulthttp://localhost:8082) +CORTEX_API_KEY- used as the ambient identity in single-tenant mode. In multi-tenant mode, each caller’s bearer token supplies the identity and ambient organization defaults are ignored.- Scoping defaults:
CORTEX_MCP_DEFAULT_PRODUCT_INSTANCE_ID,CORTEX_MCP_DEFAULT_TENANT_ID,CORTEX_MCP_DEFAULT_EXTERNAL_USER_ID. - Public URL:
https://mcp.canopy.pm, health athttps://mcp.canopy.pm/mcp/health.
Feature-gated: the platform manifest classifies cortex.mcp as
generally available and internal/staff-only. The MCP server hides all tools only
when its feature check receives an explicit disabled result. If the internal
state is not visible to its configured API key, or Cortex cannot be reached,
the check fails open and tools remain listed. Tool listing is discovery, not
authorization: Cortex still enforces each API operation’s permissions and
feature checks. A deployment operator must stop or protect the MCP service to
revoke access when its feature state cannot be resolved.
The Cortex MCP package includes training and agent-run tools. Their presence in
tools/list does not grant API permissions; each Cortex API operation still
enforces its own authorization and feature checks.
| Tool | Params | What it does |
|---|---|---|
cortex_list_knowledge_bases |
- | List active knowledge spaces |
cortex_create_knowledge_base |
name, slug, scope_type?, product_instance_id?, description? |
Create a knowledge space |
cortex_retrieve |
query, knowledge_space_id?, knowledge_space_slug?, product_instance_id?, top_k? |
Hybrid search, returns ranked chunks with source refs |
cortex_ask |
question, knowledge_space_id?, knowledge_space_slug?, product_instance_id?, assistant_id?, external_user_id?, context_type?, context_ref?, top_k?, max_new_tokens?, temperature?, top_p? |
RAG Q&A with citations |
cortex_list_projects |
name?, external_tenant_id?, product_instance_id? |
List tenants/projects |
cortex_list_documents |
tenant_id?, tenant_external_id?, scope?, include_archived?, limit? |
List ingested documents |
cortex_get_context |
- | List available knowledge bases (call first in a session) |
cortex_ask_codebase |
question, external_user_id?, top_k? |
RAG over Cortex’s own ingested codebase (needs scripts/ingest_codebase.py run first) |
cortex_remember |
content, user_id?, agent_id? |
Store a persistent memory |
cortex_recall |
query, user_id?, agent_id?, top_k? |
Search persistent memories |
cortex_ingest_and_wait |
content, name, path?, library_path?, product_instance_id?, poll_interval_seconds?, poll_timeout_seconds? |
Submit text/markdown for ingestion, poll to completion |
cortex_training_run_create |
name, base_model_name, product_instance_id?, knowledge_space_id?, dataset_id?, machine?, pool?, providers?, gpu_vendor? |
Create a pending training run; it trains on Canopy, on your own machines first and then Canopy’s GPUs unless machine (one machine), pool (a label), providers (own, canopy) or gpu_vendor (nvidia, apple) limit it |
cortex_training_run_list |
- | List training runs |
cortex_training_run_launch |
training_run_id |
Start a pending run |
cortex_training_run_cancel |
training_run_id |
Cancel a run |
cortex_training_run_status |
training_run_id |
Status/loss metrics/error |
cortex_agent_run_status |
run_id |
Read-only status/steps/chat history for an agent run |
Hosted MCP servers (marketplace)
Section titled “Hosted MCP servers (marketplace)”canopy mcp (CLI) and sdk.mcpHosting (SDK) are not a way to
connect to either server above. They manage preview hosted-server metadata
for a team. The registry supports server records, version metadata and
credential storage, but Canopy does not currently run the uploaded server:
start and invoke return an unavailable error because the runtime is not
implemented. The invoke route is a REST-shaped interface, not the MCP wire
protocol:
canopy mcp list --team <team-id>canopy mcp show <server_id> --team <team-id>canopy mcp create <name> --team <team-id> --namespace <id> --slug <slug>canopy mcp publish, set-credential, start, invoke, and install
commands are also registered. Publishing a version and storing a credential
write metadata, but start and invoke fail with an unavailable error while
the runtime is absent. install prints the REST invocation URL and tool
metadata; the endpoint is likewise unavailable for execution. It is not full
MCP-protocol (JSON-RPC/SSE) wire compatibility, so a generic MCP client cannot
use it for the standard handshake.
This feature is gated behind host.mcp.hosting, which is generally available. Although the API and CLI can create and publish server
metadata, runtime start/invocation is unavailable. See
Platform Features for the feature gate and
Host CLI for executable examples.