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 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. The org_id field on each tool is still required by the schema, but a key ignores any other value and uses its 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 ten tools: four that write and six that read. Each takes a flat set of arguments. Identifiers like org_id and initiative_id are UUIDs resolved from your workspace; you do not type them by hand in an agent conversation.

The label, goal_type, and document_type enums match the values used across ForceVue: 13 context labels, 5 goal types, and 12 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.

#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 do not change anything, so they run without a confirmation step.

#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.