Skip to main content

    MCP Tools Reference

    Reference for all 40 MCP tools — reads, writes, AI generation, and knowledge files. Includes scopes, dry-run/confirm workflow, and error codes.

    Last updated: May 20, 2026

    MCP Tools Reference

    Brand Kit OS exposes 40 tools through its MCP server, covering reads, writes, AI generation, and knowledge-file management. This page lists every tool, its required scope, and its parameters.

    Authentication

    Tools are accessible via two authentication methods:

    • OAuth 2.0 (Remote Connector): No API key needed — Claude authenticates via your Brand Kit OS account. All scopes granted by default.
    • API Key: For Cursor, Claude Code, and other MCP clients — pass your key in the Authorization: Bearer header. Scopes are key-specific — write tools require an API key minted with the matching write scope.

    Scopes

    Scope Grants
    brand_kit:read All get_* / list_* brand kit tools (default)
    brand_kit:write All upsert_*, update_*, create_*, and generate_* brand-kit tools
    knowledge_files:write upload_knowledge_file

    Read Tools

    Tool Description Parameters
    list_brand_kits Lists all brand kits the user has access to none
    get_brand_kit Returns all sections of a brand kit in a single call — core, personality, expression, audience, governance, products, personas, competitors, visuals, SEO brand_kit_id
    get_brand_kit_summary Compact overview (~500 tokens) — ideal for quick context loading brand_kit_id
    get_brand_kit_completeness Reports per-section completion percentages and missing fields brand_kit_id
    get_brand_context_for_agent Optimized agent-ready briefing combining identity, voice, and guardrails brand_kit_id
    get_brand_kit_core Mission, vision, story, promises brand_kit_id
    get_brand_kit_personality Brand values, principles, traits, moods brand_kit_id
    get_brand_kit_expression Tone of voice, verbal style, terminology, archetypes brand_kit_id
    get_brand_kit_audience Target audience personas with demographics, motivations, pain points brand_kit_id
    get_brand_kit_governance Behavioral constraints, writing rules, compliance notes brand_kit_id
    get_brand_kit_products Products/services with descriptions, pricing, USPs brand_kit_id
    get_brand_kit_personas AI personas with roles, rules, tone overrides brand_kit_id
    get_brand_kit_competitors Competitor analysis data brand_kit_id
    get_brand_kit_seo SEO keywords, tags, suggested keywords brand_kit_id
    get_brand_kit_social_profiles Connected social profiles per brand kit brand_kit_id
    get_brand_kit_logo_assets Logo asset metadata for a brand kit brand_kit_id
    get_logo_asset A single logo asset by id logo_asset_id
    list_logo_assets Lists logo assets for a brand kit brand_kit_id
    get_persona_system_prompt Compiled system prompt for a specific AI persona brand_kit_id, persona_id
    list_expression_examples Lists "do/don't" expression examples for a brand kit brand_kit_id
    list_knowledge_files Lists uploaded knowledge files for a brand kit brand_kit_id
    get_knowledge_file Returns parsed text content of a knowledge file knowledge_file_id

    Write Tools

    All write tools require the brand_kit:write scope. Competitor writes additionally enforce a server-side dry_run → confirm workflow — call once with dry_run: true to preview, then re-invoke with confirm: true to write.

    Brand kit content

    Tool Description Key Parameters
    update_brand_kit Updates the brand kit's name, description, and high-level metadata brand_kit_id, name?, description?, …
    upsert_brand_kit_core Saves mission, vision, story, promises brand_kit_id, core fields
    upsert_brand_kit_personality Saves brand values, traits, principles, moods brand_kit_id, personality fields
    upsert_brand_kit_expression Saves tone, verbal style, terminology, archetypes (and mirrors brand_voice) brand_kit_id, expression fields
    upsert_brand_kit_governance Saves behavioral and writing constraints, compliance notes brand_kit_id, governance fields
    upsert_brand_kit_seo Saves SEO keywords, tags, suggested keywords brand_kit_id, SEO fields
    update_brand_kit_visuals Updates brand colors, fonts, button styles, spacing, typography brand_kit_id, visual fields
    create_expression_example Adds a "do" or "don't" example to the expression library brand_kit_id, kind, text, notes?

    Audience & personas

    Tool Description Key Parameters
    generate_audience_persona AI-generates a new audience persona from a brief (costs 1 token) brand_kit_id, brief
    update_audience_persona Updates fields on an existing audience persona brand_kit_id, persona_id, fields
    generate_ai_persona AI-generates a new AI assistant persona (costs 1 token) brand_kit_id, brief
    update_ai_persona Updates fields on an existing AI persona brand_kit_id, persona_id, fields

    Products

    Tool Description Key Parameters
    create_brand_kit_product Creates a product/service entry brand_kit_id, name, description?, price?, usp?, …
    update_brand_kit_product Updates fields on an existing product brand_kit_id, product_id, fields

    Competitors

    Both competitor write tools enforce the two-step confirmation workflow. At least one visual-identity field (colors, fonts, tagline, value props, typography, button styles, social profiles, etc.) is required when creating.

    Tool Description Key Parameters
    create_brand_kit_competitor Adds a competitor with visual identity, social profiles, typography, button styles, spacing brand_kit_id, url, name, visual-identity fields, dry_run / confirm
    update_brand_kit_competitor Updates any subset of competitor fields brand_kit_id, competitor_id, fields, dry_run / confirm

    Logo assets

    Tool Description Key Parameters
    update_logo_asset Updates logo asset metadata (label, light/dark variant, display order) brand_kit_id, logo_asset_id, fields

    Knowledge files

    Tool Description Key Parameters
    upload_knowledge_file Uploads a knowledge file as base64; parsed and indexed for retrieval. Requires knowledge_files:write scope. brand_kit_id, file_name, mime_type, base64_content

    Confirmation contract for mutating tools

    create_brand_kit_competitor and update_brand_kit_competitor enforce a dry-run → confirm → write workflow server-side:

    1. Call with dry_run: true. Server returns the payload that would be written along with the existing row (for updates) and never touches the database.
    2. Show the preview to the user and wait for explicit approval.
    3. Re-invoke with the same arguments plus confirm: true (and dry_run omitted or false).

    Any write attempted without confirm: true is rejected with confirmation_required.

    Error codes

    Code Meaning
    confirmation_required Write attempted without confirm: true and without dry_run: true.
    validation_error Required field missing or has the wrong shape.
    scope_denied API key is missing the scope required by the tool.
    access_denied User does not own or have write access to the brand kit.
    not_found Target row does not exist or does not belong to the brand kit.
    rate_limited Per-user rate limit exceeded.
    insufficient_tokens AI-generation tools cost 1 token; the brand kit owner's pool is empty.

    Example flows

    Read full brand context

    1. list_brand_kits → user selects a kit
    2. get_brand_kit for full context or get_brand_kit_summary for the lightweight version

    Update brand voice

    1. get_brand_kit_expression to see current state
    2. upsert_brand_kit_expression with new tone / terminology

    Add a competitor (two-step)

    1. create_brand_kit_competitor with dry_run: true → preview
    2. User approves
    3. create_brand_kit_competitor with same args + confirm: true

    Generate an audience persona

    1. generate_audience_persona with a short brief (costs 1 token from the owner's pool)
    2. update_audience_persona to refine fields

    Connection methods

    These tools are available through all three connection methods:

    • Remote Connector — OAuth, no API key (setup guide)
    • Cowork Plugin — Claude Desktop plugin with skills (setup guide)
    • API Key — Cursor, Claude Code, other tools (setup guide)