# MCP Server: Overview, Authentication & Tool Catalog Gakaso exposes a Model Context Protocol (MCP) server so that an external AI agent — you — can operate a project's canvas, tokens, and related data directly, instead of going through the browser UI. This page covers how to connect and authenticate, and gives a categorized inventory of the tool surface. For the faithful-UI-import/export flow specifically, see `/mcp/faithful-roundtrip.md`. ## Transport The MCP server supports both **stdio** (for a locally-spawned agent process) and **Streamable HTTP** (for a remote/hosted agent), depending on how the connecting client is configured. Tool behavior is identical across both transports. ## Authentication and authorization: two layers Gakaso authorizes an MCP call in two independent layers. Both must pass; neither substitutes for the other. ### Layer 1 — project role (RBAC) - Every API key is issued **per project** and is owned by a specific user account (a human's account, or a service/system account) — from that project's Settings → API Keys screen, or handed to you directly. A key's Bearer token is a `gks_`-prefixed random token; treat the value as a secret and never log or echo it back in full. It is shown once at creation time; if lost, the fix is to rotate/reissue (`gakaso_rotate_api_key`), not to "look it up" — only a short prefix is ever retrievable afterward. - Each key's calling identity has a **role** on the project, from the project's membership list (see `/team/management.md`): `owner`, `editor`, `agent`, or `viewer`. - Each role maps to one or more of three permission levels, checked on essentially every project-scoped tool call: | Role | Permissions | |---|---| | `owner` | `read`, `write`, `admin` | | `editor` | `read`, `write` | | `agent` | `read`, `write` (same practical level as `editor`) | | `viewer` | `read` only | - Read-only tools (`gakaso_get_*`, `gakaso_list_*`, etc.) require `read`. Mutating tools (create/update/delete/import/export/publish) require `write`. A small set of project-governance tools — notably adding, changing, or removing **members** via `gakaso_manage_project_members` (see `/team/management.md`) — require `admin`, so a key held by an `editor`/`agent`-role identity can fully author canvas content but cannot change who else has access. - A call whose calling identity lacks the required permission is rejected as a `FORBIDDEN` error (see error table below), not silently downgraded. ### Layer 2 — capability scopes (`frame:import` / `frame:export`) - Independently of project role, a key also carries a set of **scopes** (`project:read`, `project:write`, `canvas:read`, `canvas:write`, `token:read`, `token:write`, `export:read`, `frame:import`, `frame:export`, `admin`, `*`). The API Keys screen offers **read** / **write** / **agent** presets that map onto sensible scope bundles, or a human can grant scopes individually. - As currently implemented, the scope check is actively enforced only at the **faithful-round-trip boundary** (see `/mcp/faithful-roundtrip.md`): `gakaso_import_ui_snapshot`, `gakaso_import_app_snapshot`, and `gakaso_import_live_url` each require the `frame:import` scope; `gakaso_export_faithful` requires `frame:export`. A key with an empty scope list, `["*"]`, or `"admin"` always passes this check (full-access backward-compat). For every other tool, access is governed purely by Layer 1 (project role) — granting/withholding `canvas:write`, `token:write`, etc. on a key does not currently change what that tool will do. Don't rely on narrower scopes to restrict a key's access to non-frame tools; use project role (viewer vs. editor/agent) for that instead. - If a task fails with `INSUFFICIENT_SCOPE`, the fix is for the human to reissue the key with `frame:import`/`frame:export` added — you cannot escalate your own key's scope from within a session. - Every key is bound to a single project — you cannot use one project's key to reach another project's data, regardless of scope. ## Rate limits Rate limits are configurable per key via `gakaso_get_rate_limits` / `gakaso_set_rate_limits` (defaults: 60 requests/minute, 1000/hour, with a lockout after repeated overages) — see `/billing.md` for how this interacts with plan tier. If you're doing a bulk operation, prefer the batch tools (`gakaso_batch_add_components`, `gakaso_batch_update_components`, `gakaso_batch_delete_components`) over looping single-object calls. ## Unauthenticated static resources Two resource families require **no** API key or project binding — they're static reference material, not project data: - `gakaso://diagram-templates/index`, `gakaso://diagram-templates/{category}` — diagram template taxonomy (see `/design/diagram-intelligence.md`) - `gakaso://manuals/diagram-selection`, `gakaso://manuals/design-principles` — agent-facing selection/design guidance (see `/design/diagram-intelligence.md`) Everything else (canvas state, tokens, history, etc.) is project-scoped and requires an authenticated, project-bound key. ## Tool catalog by category Gakaso's MCP surface currently registers 137 `gakaso_*` tools (plus two unauthenticated meta-tools, `ping` and `list-capabilities`, useful for a quick liveness/discovery check before you have a project key). Tools are named `gakaso_<snake_case_action>`. Below is the full set grouped by what they operate on. Consult each tool's own `inputSchema`/description at connect time for exact parameters — this list is for discovery, not a full API reference. If your MCP client supports it, `list-capabilities` returns a flat name+description array of the whole surface in one call, which is often faster than reading this document when you just need the name of something you already know exists. **Projects & project groups** `gakaso_create_project`, `gakaso_get_project`, `gakaso_list_projects`, `gakaso_create_project_group`, `gakaso_assign_project_to_group`, `gakaso_delete_project_data` `gakaso_create_project` takes `name`, optional `description`, optional `kind` (`application` default, or `diagram`), `diagramKind` (required when `kind="diagram"` — see `/canvas/diagram-mode.md`), and an optional `targetPlatform`: `web` (default), `ios`, `android`, `macos`, `windows`, `react-native`, or `flutter`. `targetPlatform` is what tells later faithful-export calls which native format to eventually generate toward (see the `swiftui`/`compose` formats in `/mcp/faithful-roundtrip.md`) — set it up front rather than trying to change it per-export-call. **Team / member management** (see `/team/management.md`) `gakaso_manage_project_members` **Pages** `gakaso_create_page`, `gakaso_get_page`, `gakaso_list_pages`, `gakaso_update_page`, `gakaso_delete_page` **Canvas components (application & diagram mode)** `gakaso_add_component`, `gakaso_update_component`, `gakaso_delete_component`, `gakaso_list_components`, `gakaso_query_components`, `gakaso_get_canvas`, `gakaso_batch_add_components`, `gakaso_batch_update_components`, `gakaso_batch_delete_components`, `gakaso_group_components`, `gakaso_align_components`, `gakaso_distribute_components`, `gakaso_link_component`, `gakaso_list_linked_components`, `gakaso_link_semantic_relation`, `gakaso_get_relations` **Variants, breakpoints, themes** `gakaso_create_variant`, `gakaso_list_variants`, `gakaso_switch_variant`, `gakaso_set_breakpoints`, `gakaso_get_responsive_layout`, `gakaso_create_theme`, `gakaso_switch_theme` **Diagram-specific** `gakaso_diagram_auto_layout` (see `/canvas/diagram-mode.md`) **Design tokens** (see `/design/tokens.md`) `gakaso_create_token`, `gakaso_update_token`, `gakaso_delete_token`, `gakaso_list_tokens`, `gakaso_import_tokens`, `gakaso_export_tokens`, `gakaso_distribute_tokens`, `gakaso_resolve_token_alias`, `gakaso_propagate_token_change`, `gakaso_analyze_token_usage` **Visual detail: effects, images, icons, SVG** `gakaso_apply_effect`, `gakaso_remove_effect`, `gakaso_apply_image_filter`, `gakaso_add_icon`, `gakaso_search_icons`, `gakaso_import_svg`, `gakaso_export_svg` **Interactions / prototyping** `gakaso_define_interaction`, `gakaso_list_interactions` **AI chat / suggestions** `gakaso_ai_chat`, `gakaso_ai_suggest` **Product Design Capsule** (per-project design brief: purpose, audience, aesthetic direction, tokens, anti-patterns) `gakaso_set_design_capsule`, `gakaso_get_design_capsule` — see `/design/product-design-capsule.md` for the full capsule shape. **Faithful round-trip** (see `/mcp/faithful-roundtrip.md`) `gakaso_import_ui_snapshot`, `gakaso_import_app_snapshot`, `gakaso_import_live_url`, `gakaso_export_faithful`, `gakaso_get_ui_snapshot` **Figma import** `gakaso_import_figma_file` **Code / spec export** (see `/export.md`) `gakaso_export_code`, `gakaso_export_design_spec`, `gakaso_export_intermediate`, `gakaso_export_high_res`, `gakaso_generate_code_samples`, `gakaso_generate_stateful_code`, `gakaso_scan_exported_code`, `gakaso_spec_get`, `gakaso_spec_lint`, `gakaso_spec_reconcile`, `gakaso_get_schema_version` **Architecture / requirements / scaffolding** `gakaso_register_app_architecture`, `gakaso_import_architecture`, `gakaso_import_requirements`, `gakaso_generate_tech_spec`, `gakaso_scaffold_from_techspec`, `gakaso_analyze_codebase` **GitHub / change management** `gakaso_create_github_pr`, `gakaso_generate_changeset`, `gakaso_analyze_change_impact` **Sync state (canvas ↔ generated code)** `gakaso_sync_status`, `gakaso_sync_diff`, `gakaso_sync_resolve`, `gakaso_drift_resolve`, `gakaso_check_consistency` **Human-review workflow** `gakaso_submit_for_review`, `gakaso_approve_design`, `gakaso_reject_design`, `gakaso_list_pending_reviews`, `gakaso_optimize_after_human_edit`, `gakaso_add_annotation`, `gakaso_list_annotations`, `gakaso_resolve_annotation` **History / snapshots / branching** `gakaso_list_history`, `gakaso_get_history`, `gakaso_restore_version`, `gakaso_compare_snapshots`, `gakaso_restore_snapshot`, `gakaso_create_branch`, `gakaso_list_branches`, `gakaso_merge_branch` **Templates** `gakaso_list_templates`, `gakaso_create_from_template`, `gakaso_save_as_template` **Visual QA / accessibility** `gakaso_get_computed_a11y_tree`, `gakaso_get_computed_styles`, `gakaso_audit_accessibility`, `gakaso_a11y_check`, `gakaso_render_snapshot`, `gakaso_render_batch`, `gakaso_verify_visual_fidelity`, `gakaso_visual_regression_test` **Webhooks** `gakaso_register_webhook`, `gakaso_list_webhooks`, `gakaso_delete_webhook`, `gakaso_verify_webhook_signature`, `gakaso_subscribe_changes` **Security / governance** `gakaso_set_data_classification`, `gakaso_set_data_retention`, `gakaso_query_audit_log`, `gakaso_rotate_api_key`, `gakaso_set_key_expiry`, `gakaso_get_rate_limits`, `gakaso_set_rate_limits` **i18n** `gakaso_manage_locales`, `gakaso_set_text_locale` **Publishing** `gakaso_publish_doc` — see `/publish-doc.md` for the full tool contract (params, slug rules, classification gate). **Operations / metrics** `gakaso_execute_workflow`, `gakaso_get_usage_metrics`, `gakaso_get_hub_dashboard`, `gakaso_upload_asset` ## MCP resources vs. tools The two unauthenticated static resource families above (diagram templates, manuals) are currently the full set of MCP **resources** Gakaso exposes. Project-specific data — canvas state, pages, tokens, history, and so on — is read through the **tool** calls listed below (e.g. `gakaso_get_canvas`, `gakaso_list_components`, `gakaso_get_page`, `gakaso_list_tokens`), not through a `resources/read` call on a project URI. If you're used to other MCP servers exposing per-entity resource URIs, don't assume Gakaso does the same for project data — use the corresponding `get`/`list` tool instead. ## Error codes Every tool response is `{ content: [{ type: "text", text: <JSON> }] }`; on failure the JSON body is `{ error: true, code, message }`. The application-defined codes actually used across the tool surface are: | Code | Name | Meaning | |---|---|---| | `-32000` | `AUTH_ERROR` | No/invalid API key, or `MCP_USER_ID` missing in stdio/self-hosted mode | | `-32001` | `NOT_FOUND` | Referenced project/page/component/token/key doesn't exist (this single code covers all "not found" cases — Gakaso does not use a separate code per entity type) | | `-32002` | `CONFLICT` | e.g. a member is already on the project, a publish slug is taken by another project | | `-32003` | `FORBIDDEN` | Calling identity's project role lacks the required permission (see Authorization above), or (for API-key tools) it isn't the key's own owner | | `-32011` | `INSUFFICIENT_SCOPE` | Key lacks a required scope (currently only raised for `frame:import` / `frame:export`) | Standard JSON-RPC-level codes can also surface: `-32700` `PARSE_ERROR`, `-32600` `INVALID_REQUEST`, `-32601` `METHOD_NOT_FOUND`, `-32602` `INVALID_PARAMS` (malformed/out-of-range input — e.g. a bad slug, a non-ISO-8601 expiry date), `-32603` `INTERNAL_ERROR`. There is no dedicated "rate limited" or "project not found vs. object not found" distinction beyond the table above — if you were expecting a more granular code (e.g. one specific to "canvas full" or "sync conflict"), it doesn't exist; the `message` string is where tool-specific detail lives, so surface it to the human rather than branching only on `code`. ## A note on tone Everything above is discovery-level: enough for you to know what exists and where to look next. It is not a full parameter reference — read each tool's own schema at connect time, and read `/mcp/faithful-roundtrip.md`, `/design/tokens.md`, `/design/product-design-capsule.md`, `/team/management.md`, `/security/model.md`, `/publish-doc.md`, and `/export.md` for the topics that need more than a one-line description.