{"serverInfo":{"name":"Colma MCP","version":"1.0.0","description":"Workspace-aware SEO strategy MCP for Colma organizations."},"protocolVersion":"2025-11-25","transport":{"type":"streamable-http","url":"https://app.colma.ai/mcp"},"authentication":{"required":true,"schemes":["oauth2"],"authorizationServer":"https://app.colma.ai/.well-known/oauth-authorization-server","protectedResource":"https://app.colma.ai/.well-known/oauth-protected-resource"},"homepage":"https://www.colma.ai/mcp","documentation":"https://app.colma.ai/dashboard/mcp","logo":"https://app.colma.ai/colma-dot-cluster-512.png","icon":"https://app.colma.ai/favicon.ico","categories":["SEO","Marketing","Workflows","Workspace"],"tools":[{"name":"list_workspaces","description":"Find the Colma client workspaces this authenticated organization can access. Use this before workspace-specific tools so the agent can choose the correct site and pass its workspaceId.","inputSchema":{"type":"object","properties":{},"required":[]},"annotations":{"title":"List Workspaces","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"select_workspace","description":"Set the default workspace for this MCP token after the user chooses a client site. This helps resources point at the right workspace, but workspace-specific tools still accept an explicit workspaceId.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."}},"required":["workspaceId"]},"annotations":{"title":"Select Workspace","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"get_site_context","description":"Get a compact briefing for a client site: workspace name, domains, primary URL, recent jobs, and available strategy files. Use this to answer questions about a site or plan an investigation.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."}},"required":["workspaceId"]},"annotations":{"title":"Get Site Context","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_workspace_files","description":"List visible strategy and research files in a client workspace. Use this to discover prior outputs before reading, editing, or launching dependent SEO V2 workflows.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."}},"required":["workspaceId"]},"annotations":{"title":"List Workspace Files","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"read_workspace_file","description":"Read the full contents of a visible text file in a workspace, such as an audit summary, keyword research output, strategy note, CSV, JSON, or markdown report.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"filename":{"type":"string","description":"Visible workspace file path, such as strategy-notes.md or company_intake_summary.md. Hidden dotfiles are not exposed."}},"required":["workspaceId","filename"]},"annotations":{"title":"Read Workspace File","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"search_workspace_files","description":"Search visible workspace text files for a phrase or entity. Use this when the user asks whether prior research mentions a topic, page, keyword, competitor, recommendation, or issue.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"query":{"type":"string","description":"Case-insensitive phrase to search for across visible text-like workspace files."},"maxFiles":{"type":"integer","default":50,"description":"Maximum number of visible files to inspect, capped by the server."},"maxMatches":{"type":"integer","default":20,"description":"Maximum number of snippets to return, capped by the server."}},"required":["workspaceId","query"]},"annotations":{"title":"Search Workspace Files","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"write_workspace_file","description":"Create or replace a visible workspace file with new content and a history backup. Use for deliberate updates to strategy docs, generated reports, or structured artifacts.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"filename":{"type":"string","description":"Visible workspace file path, such as strategy-notes.md or company_intake_summary.md. Hidden dotfiles are not exposed."},"content":{"type":"string","description":"Complete replacement content for the target file."}},"required":["workspaceId","filename","content"]},"annotations":{"title":"Write Workspace File","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},{"name":"append_workspace_file","description":"Append content to a visible workspace file without replacing the existing document. Use for logs, notes, addenda, and incremental findings.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"filename":{"type":"string","description":"Visible workspace file path, such as strategy-notes.md or company_intake_summary.md. Hidden dotfiles are not exposed."},"content":{"type":"string","description":"Content to append to the end of the target file."}},"required":["workspaceId","filename","content"]},"annotations":{"title":"Append Workspace File","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"replace_in_workspace_file","description":"Replace the first exact text occurrence in a visible workspace file. Use for targeted edits when the agent can quote the exact text to change.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"filename":{"type":"string","description":"Visible workspace file path, such as strategy-notes.md or company_intake_summary.md. Hidden dotfiles are not exposed."},"oldText":{"type":"string","description":"Exact existing text to replace. The server changes only the first occurrence."},"newText":{"type":"string","description":"Replacement text."}},"required":["workspaceId","filename","oldText","newText"]},"annotations":{"title":"Replace In Workspace File","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},{"name":"edit_workspace_section","description":"Replace an existing markdown section by heading, or append it if the heading is missing. Use for updating a named strategy section while preserving the rest of the file.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"filename":{"type":"string","description":"Visible workspace file path, such as strategy-notes.md or company_intake_summary.md. Hidden dotfiles are not exposed."},"heading":{"type":"string","description":"Markdown heading to replace or append, including # characters, such as ## Priority Actions."},"content":{"type":"string","description":"New body content for the section, without repeating the heading."}},"required":["workspaceId","filename","heading","content"]},"annotations":{"title":"Edit Workspace Section","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":false}},{"name":"save_strategy_note","description":"Save a timestamped strategy note to strategy-notes.md for the client workspace. Use proactively when the chat establishes decisions, hypotheses, next steps, or durable context worth preserving.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"title":{"type":"string","description":"Short note title, such as Investigation Plan or Keyword Focus Decision."},"content":{"type":"string","description":"Strategy note body with the context, decision, rationale, or next steps to preserve."}},"required":["workspaceId","title","content"]},"annotations":{"title":"Save Strategy Note","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"list_v2_workflows","description":"List the client-facing SEO V2 investigations and workflows available through Colma MCP, including credits, required inputs, and dependency file hints.","inputSchema":{"type":"object","properties":{},"required":[]},"annotations":{"title":"List V2 Workflows","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_program_templates","description":"List Colma SEO program templates available to this organization. Use this before launching a full auto-continuing program when the user asks for a guided SEO program rather than a one-off workflow.","inputSchema":{"type":"object","properties":{},"required":[]},"annotations":{"title":"List Program Templates","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_billing_status","description":"Check the organization billing mode, plan, and credit balance before launching billable workflows.","inputSchema":{"type":"object","properties":{},"required":[]},"annotations":{"title":"Get Billing Status","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"validate_v2_workflow_launch","description":"Validate a planned SEO V2 workflow launch before spending credits. Returns inferred website URL, required input warnings, missing dependency files, duplicate risk, and credit cost.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"workflowSlug":{"type":"string","description":"SEO V2 workflow slug from list_v2_workflows, for example preliminary-keyword-research-v2-cf."},"params":{"type":"object","description":"Workflow-specific launch parameters. Include website_url when the workspace primary URL should be overridden."}},"required":["workspaceId","workflowSlug"]},"annotations":{"title":"Validate V2 Workflow Launch","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"launch_v2_workflow","description":"Launch a billable SEO V2 investigation or workflow for a client workspace. Use after validate_v2_workflow_launch when the user wants Colma to run research, audits, keyword work, content strategy, or synthesis.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"workflowSlug":{"type":"string","description":"SEO V2 workflow slug from list_v2_workflows, for example preliminary-keyword-research-v2-cf."},"params":{"type":"object","description":"Workflow-specific launch parameters. The server injects workspace strategy context and a website_url when available."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId","workflowSlug"]},"annotations":{"title":"Launch V2 Workflow","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_keyword_research","description":"Launch Colma's SEO V2 preliminary keyword research for a client workspace. Use when the user asks for keyword research, opportunity discovery, keyword groups, clusters, or candidate SEO themes.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"industry":{"type":"string","description":"Optional industry, market, or vertical context to guide research."},"competitors":{"type":"string","description":"Optional competitor domains or company names, comma-separated or one per line."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId"]},"annotations":{"title":"Run Keyword Research","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_deep_keyword_research","description":"Launch the production deep keyword research workflow with seed keywords. Use when the user gives seed terms and wants expanded keyword ideas, search opportunity analysis, competitors, and target-location keyword data.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"seedKeywords":{"type":"string","description":"Required seed keywords, comma-separated or one per line."},"industry":{"type":"string","description":"Optional industry, market, or vertical context to guide research."},"competitors":{"type":"string","description":"Optional competitor domains or company names, comma-separated or one per line."},"targetLocation":{"type":"string","enum":["United States","United Kingdom","Canada","Australia","Germany","France"],"default":"United States","description":"Geographic market for keyword data."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId","seedKeywords"]},"annotations":{"title":"Run Deep Keyword Research","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_keyword_ranking_analysis","description":"Launch current keyword ranking analysis for a client workspace. Use when the user asks where the site ranks today, which themes are performing, or how current ranking coverage looks.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"industry":{"type":"string","description":"Optional industry, market, or vertical context to guide research."},"keywordThemes":{"type":"string","description":"Optional keyword themes to check, one per line. Leave blank for workflow discovery."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId"]},"annotations":{"title":"Run Keyword Ranking Analysis","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_technical_site_audit","description":"Launch a billable technical SEO site audit for crawlability, indexability, PageSpeed/Core Web Vitals, status codes, metadata coverage, content quality, and prioritized technical recommendations.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"crawlDepth":{"type":"integer","enum":[100,250,500],"default":100,"description":"Maximum number of pages to crawl."},"technicalFocus":{"type":"string","description":"Optional known technical issues or areas to prioritize, such as migration, indexing, slow pages, or canonical problems."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId"]},"annotations":{"title":"Run Technical Site Audit","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_competitor_research","description":"Launch SEO V2 competitor research for a client workspace. Use when the user asks to identify search competitors, compare competitor strategy, or gather competitor context before keyword and content planning.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"industry":{"type":"string","description":"Optional industry, market, or vertical context to guide research."},"competitors":{"type":"string","description":"Optional competitor domains or company names, comma-separated or one per line."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId"]},"annotations":{"title":"Run Competitor Research","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"run_page_optimization_plan","description":"Launch SEO V2 page optimization planning for a client workspace. Use when the user asks which existing pages to preserve, improve, merge, or create for selected keyword themes.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"companyName":{"type":"string","description":"Optional company or brand name to pass to the workflow."},"params":{"type":"object","description":"Advanced workflow-specific parameters. These are merged with the named fields on this tool."},"acknowledgeWarnings":{"type":"boolean","description":"Set true only after reviewing validation warnings, missing dependency files, or duplicate-job risk with the user."},"skipDedup":{"type":"boolean","description":"Set true to bypass duplicate-job protection when intentionally rerunning a workflow."}},"required":["workspaceId"]},"annotations":{"title":"Run Page Optimization Plan","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"launch_seo_program","description":"Create a full Colma SEO program for a workspace and optionally start the ProgramAgent so it can auto-continue through available automated steps. Use this when the user asks to launch a program, ongoing SEO plan, guided audit/research sequence, or auto-continuing investigation.","inputSchema":{"type":"object","properties":{"workspaceId":{"type":"string","description":"Colma workspace ID for the client site. Use list_workspaces first, then pass the selected workspaceId explicitly."},"programType":{"type":"string","enum":["seo-dev","seo-dev-dual","seo-wizard","existing-client-setup","seo-v2"],"default":"seo-v2","description":"Colma program template slug. Use list_program_templates first when unsure."},"websiteUrl":{"type":"string","description":"Optional website URL override. If omitted, Colma uses the selected workspace primary domain."},"domains":{"type":"array","items":{"type":"string"},"description":"Optional domain list for multi-domain program templates. Single-domain programs usually use the selected workspace primary domain."},"autoContinue":{"type":"boolean","default":true,"description":"When true, initialize the ProgramAgent and send a start message so it begins work immediately."},"progressionMode":{"type":"string","enum":["auto","med","step"],"default":"auto","description":"ProgramAgent progression preference. auto continues through normal automated steps; med pauses for important questions; step waits after each automated result."},"startMessage":{"type":"string","description":"Optional initial instruction for the ProgramAgent. Defaults to starting the selected program and continuing automatically where allowed."}},"required":["workspaceId"]},"annotations":{"title":"Launch Seo Program","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"get_program_status","description":"Read a Colma program's stored status, phase, progress counts, process snapshot, and recent jobs. Use after launching a program or when the user asks what a program is doing.","inputSchema":{"type":"object","properties":{"programId":{"type":"string","description":"Colma program ID returned by launch_seo_program."}},"required":["programId"]},"annotations":{"title":"Get Program Status","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"check_job_status","description":"Check the status of a Colma workflow job launched from MCP or the web app, including running, completed, failed, and summary metadata.","inputSchema":{"type":"object","properties":{"jobId":{"type":"string","description":"Colma job ID returned by launch_v2_workflow or visible in recent site context."}},"required":["jobId"]},"annotations":{"title":"Check Job Status","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"read_job_results","description":"Read the report, result files, and structured output for a completed Colma workflow job. Use to summarize findings or continue strategy work after an investigation finishes.","inputSchema":{"type":"object","properties":{"jobId":{"type":"string","description":"Colma job ID returned by launch_v2_workflow or visible in recent site context."}},"required":["jobId"]},"annotations":{"title":"Read Job Results","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"scrape_page","description":"Fetch a public web page and return SEO-relevant basics: HTTP status, title, meta description, canonical URL, heading-like text, and visible copy summary.","inputSchema":{"type":"object","properties":{"url":{"type":"string","description":"Fully qualified URL to inspect, including https://."}},"required":["url"]},"annotations":{"title":"Scrape Page","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"discover_urls","description":"Fetch a public web page and extract links for quick site discovery, internal URL sampling, sitemap planning, and crawl investigation.","inputSchema":{"type":"object","properties":{"url":{"type":"string","description":"Fully qualified URL to inspect, including https://."},"limit":{"type":"integer","default":50,"description":"Maximum number of links to return, capped by the server."}},"required":["url"]},"annotations":{"title":"Discover Urls","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"diagnose_crawlability","description":"Diagnose whether a public URL is reachable and whether robots.txt is available. Use as a lightweight crawlability check before deeper technical SEO work.","inputSchema":{"type":"object","properties":{"url":{"type":"string","description":"Fully qualified URL to inspect, including https://."}},"required":["url"]},"annotations":{"title":"Diagnose Crawlability","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"detect_site_technology","description":"Infer basic site technology from public HTTP headers and HTML markers, including WordPress, Shopify, Next.js, Webflow, Squarespace, server hints, and generator tags.","inputSchema":{"type":"object","properties":{"url":{"type":"string","description":"Fully qualified URL to inspect, including https://."}},"required":["url"]},"annotations":{"title":"Detect Site Technology","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"fetch_pagespeed","description":"Fetch a Google PageSpeed Insights summary for a public URL when a Google API key is configured, including performance, accessibility, and SEO scores.","inputSchema":{"type":"object","properties":{"url":{"type":"string","description":"Fully qualified URL to inspect, including https://."},"strategy":{"type":"string","enum":["mobile","desktop"],"default":"mobile","description":"PageSpeed strategy to run."}},"required":["url"]},"annotations":{"title":"Fetch Pagespeed","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}}],"resources":[{"uri":"colma://v2-workflows","name":"SEO V2 Workflow Catalog","mimeType":"application/json"}],"prompts":[]}