MCP server

ForceVue runs a Model Context Protocol (MCP) server so any MCP-compatible agent (Claude Desktop, Cursor, and others) can read and write your workspace: create initiatives, context items, goals, and document drafts, and list, fetch, and search what is already there.

Create an API key first. The recommended way to connect is with a workspace API key, so set one up before you start. See API keys.

#Endpoint and transport

• Endpoint: https://forcevue.com/api/mcp
• Transport: Streamable HTTP
• GET /api/mcp returns a public manifest (no auth) listing the tools and their input schemas.
• POST /api/mcp is the JSON-RPC handler. It requires authentication.

#Authentication

The server accepts two kinds of bearer token. An API key is the recommended choice for agents.

#API key (recommended)

Create a key in Workspace Settings → API Keys (paid and internal tiers, owner or admin only). Keys start with fvk_live_, are scoped to one workspace, and act on your behalf. Send the key as a bearer token:

Authorization: Bearer fvk_live_your_key_here

A key is long-lived, so the connection does not break when a browser session ends. Because the key is bound to one workspace, every tool reads and writes that workspace only. You never supply a workspace id: the server binds each call to the key's own workspace, so a key can never reach across to another workspace.

The same key drives the REST API. One credential covers both surfaces.

#Supabase JWT (fallback)

You can also send a Supabase JWT from your ForceVue session:

Authorization: Bearer your-supabase-jwt

The token identifies you and resolves your workspace and plan. A JWT is short-lived and expires with your session, so the connection stops working when the session ends and you have to fetch a fresh token. Prefer an API key for anything you want to keep running.

A JWT connection targets your personal workspace only. To work in a team or client workspace over MCP, create an API key inside that workspace (keys are bound to the workspace they are created in) and use it instead.

#The tools

There are twenty tools across four groups: four that write, six that read, six that run advisor analysis, and four that work with context coverage and classification. Each takes a flat set of arguments. You never pass a workspace id: the server binds every call to your key's workspace, so org_id is not an argument you supply. Other identifiers like initiative_id are UUIDs you get back from the list and search tools.

The label, goal_type, and document_type enums match the values used across ForceVue: 14 context labels, 5 goal types, and 13 document types. The exact allowed values are published in the input schemas of the public manifest at GET /api/mcp.

#Write tools

#create_initiative

Creates a new top-level initiative (a bare shell you fill in afterwards).

#create_context_item

Saves a labeled context item to an initiative or to the workspace.

#create_goal

Creates a goal for an initiative or the workspace.

#generate_document

Creates a document draft for an initiative. It creates a stub document that you open in ForceVue to generate the AI content. It does not write the document body over MCP.

#Read tools

Read tools return the same shapes as the REST API. List tools paginate with limit (1-100, default 20) and offset (default 0).

#list_initiatives

Lists initiatives in a workspace.

#list_documents

Lists document summaries (no body). Filter to one initiative if you want.

#get_document

Fetches one document, including its content as markdown.

Returns title, type, status, version, and content_markdown. A missing or cross-workspace id returns a uniform not-found, so an id can never tell an agent whether a document exists in another workspace.

#list_context_items

Lists context items at workspace scope, or for one initiative.

#list_goals

Lists goals at workspace scope, or for one initiative. Same fields as list_context_items.

#search_workspace

Runs a hybrid search across the workspace (documents, initiatives, context items, goals, and uploads).

Each result carries a type, id, title, snippet, url, and a relevance score. Search is scoped to your workspace, so results never include another workspace's content.

#Advisor tools

The six advisor tools run structured analysis and return suggestions or reports. Each consumes one AI rate-limit slot. Advisor tools are non-interactive: the analysis runs and results come back in the tool response, with no streaming.

#advisor_prd_critic

Reviews a PRD or similar document draft and returns anchored improvement suggestions. Each suggestion includes an exact quote from the document so your agent can locate the relevant passage.

#advisor_assumption_map

Surfaces hidden assumptions in a document draft and flags which are validated, unvalidated, or risky.

#advisor_launch_readiness

Assesses how ready an initiative is to launch based on its context, documents, and goals.

#advisor_prioritization

Analyzes an initiative's backlog or roadmap context and returns a structured prioritization perspective.

#advisor_stakeholder_update

Drafts a stakeholder update for a given audience (engineering, executive, sales, or customer success) based on the initiative's context and status.

#advisor_competitive_battlecard

Produces a competitive battlecard for a named competitor, grounded in the initiative's context items.

#Context coverage and classification tools

These four tools are the programmatic surface behind the in-app context coverage panel and the "paste anything" classifier. They help an agent understand what context an initiative already has, fill gaps before generating a document, and fix mislabeled items.

#check_context_coverage

Runs a deterministic, no-LLM coverage check. Returns an adequacy verdict and a per-slot checklist for an initiative and a given document type. Use this before generate_document to see what context is most valuable to add.

The response includes adequate (boolean), a coverage checklist of per-slot verdicts, and metrics counts for context items, goals, related docs, and uploads.

#classify_context

Splits a pasted text blob into typed context-item proposals using one structured AI call. Returns proposals without writing anything. The suggested flow is: call classify_context, review proposals in your agent, then call create_context_items to persist the ones you want.

Consumes one AI rate-limit slot (same budget as advisor_* tools).

#create_context_items

Batch-creates multiple context items for an initiative in one call. This is the confirm-write step after classify_context. Labels are re-validated server-side; an invalid label returns an error.

#relabel_context_item

Changes a single context item's label. The item must belong to an initiative in the workspace. No new row is created; only the label column is updated.

#Setup

#Claude Desktop

Add ForceVue to your Claude Desktop MCP config (claude_desktop_config.json). The recommended setup uses an API key:

{
  "mcpServers": {
    "forcevue": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://forcevue.com/api/mcp",
        "--header",
        "Authorization: Bearer ${FORCEVUE_API_KEY}"
      ],
      "env": {
        "FORCEVUE_API_KEY": "fvk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The ForceVue tools appear in the tools list. To use a session JWT instead, put the token in FORCEVUE_API_KEY in its place; the header is the same.

#Cursor

Add ForceVue to your Cursor MCP config (~/.cursor/mcp.json or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "forcevue": {
      "url": "https://forcevue.com/api/mcp",
      "headers": {
        "Authorization": "Bearer fvk_live_your_key_here"
      }
    }
  }
}

Cursor connects to the Streamable HTTP endpoint directly. Swap in a Supabase JWT if you are using the fallback path.

#Rate limits

MCP traffic counts against the same per-minute AI budget as in-app chat and generation, keyed to your account. The limits are: Free 30, Pro 60, Team 120, Consultant 240 requests per minute. When you exceed the limit the server returns 429 with a Retry-After header. See Usage & limits.

Every tool call, read or write, is audit-logged in your workspace activity so MCP actions are distinguishable from in-app actions.

#Confirmation

In the ForceVue app, the four write actions appear as confirmation cards before anything is written. Over MCP, the tools execute when the client calls them, and the MCP client handles confirmation in its own interface. Review what your agent is about to do in your client before you let the call through. Read tools, advisor tools, and check_context_coverage do not change anything, so they run without a confirmation step. classify_context also returns only proposals without writing; the write happens when you call create_context_items. Note that classify_context still runs an AI call and uses an AI rate-limit slot each time, even though it writes nothing.

#Where to go next

• REST API overview for the full HTTP API, which uses the same API key.
• Workspace chat for the same actions inside ForceVue.