colloquial-mcp-server

A Model Context Protocol (MCP) server for Colloquial. It gives AI assistants access to the fact cards in your Colloquial workspace — reading, creating and updating them, their relations, and their facts.

Tools

All fourteen topic collections (apps, assets, capabilities, features, goals, influences, information, initiatives, processes, products, services, stakeholders, strategies, technologies) share one underlying Fact Card model, so the fact card tools take a topic_type parameter rather than existing once per collection.

| Tool | Title | Description | | --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | find-fact-cards | Find Fact Cards | List the fact cards of one topic type. Returns each card's ID, name, description, and aliases. | | get-fact-card | Get Fact Card | Fetch one fact card by its type and UUID, including its fact_set, tag and group memberships, and connections. | | create-fact-card | Create Fact Card | Create a new fact card of the given topic type. | | update-fact-card | Update Fact Card | Update a fact card's fields, or archive/restore it. | | delete-fact-card | Delete Fact Card | Permanently delete a fact card. | | list-relations | List Relations | List relations (typed connections) between fact cards, filtered by types and/or pattern. Paginated. | | get-relation | Get Relation | Fetch an individual relation by UUID. | | create-relation | Create Relation | Create a relation between two fact cards (e.g. an app depends on a technology). | | update-relation | Update Relation | Update a relation's endpoints, pattern or definition. | | delete-relation | Delete Relation | Permanently delete a relation. | | list-facts | List Facts | List facts (dated attribute records) across the workspace or for one fact card, filtered by kind, template and state. Paginated. | | list-fact-templates | List Fact Templates | List the fact templates a card can carry (optionally per topic type), with each template's priority (required/recommended/optional), response_type and a value_hint for building create-fact. | | get-fact | Get Fact | Fetch an individual fact by kind and id. | | create-fact | Create Fact | Record a fact against a fact card, with a kind-specific value payload. | | renew-fact | Renew Fact | Renew a fact: a freshly-dated copy supersedes the original. | | list-groups | List Groups | List the hierarchical groups fact cards can belong to. | | get-group | Get Group | Fetch an individual group by UUID. | | create-group | Create Group | Create a group, optionally with value stages (root groups only). | | update-group | Update Group | Update a group's fields, hierarchy position, or value stages. | | delete-group | Delete Group | Permanently delete a group (fails if it has child groups). | | list-tag-groups | List Tag Groups | List all tag groups and their tags (source of tag_ids). | | get-tag-group | Get Tag Group | Fetch an individual tag group by id. | | create-tag-group | Create Tag Group | Create a new tag group. | | update-tag-group | Update Tag Group | Update a tag group's fields or status. | | delete-tag-group | Delete Tag Group | Permanently delete a tag group. | | list-tags | List Tags | List tags, filtered by tag group and/or status. Paginated. | | get-tag | Get Tag | Fetch an individual tag by id. | | create-tag | Create Tag | Create a new tag within a tag group. | | update-tag | Update Tag | Update a tag's fields, tag group, or status. | | delete-tag | Delete Tag | Permanently delete a tag. | | list-users | List Users | List all workspace users (source of user_id for fact contributions). |

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can gate write and delete operations appropriately. API validation errors (HTTP 422) are returned to the model verbatim so it can correct its input.

Prompts

The server also registers MCP prompts — guided, multi-step templates a host can offer the user (e.g. as a slash command). A prompt performs no API calls itself; it steers the assistant to call the tools above in the right order.

| Prompt | Title | Description | | ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create-fact-card-guided | Create Fact Card (guided) | Walks through creating a card: name → description → group search & assignment (via list-groups) → tag recommendation (via list-tag-groups) → create-fact-card → a Required/Recommended facts quiz driven by list-fact-templates. Optional args: topic_type, name. |

Prerequisites

• Node.js v18 or higher
• A Colloquial workspace with an API token

Configuration

| Environment variable | Required | Description | | ---------------------- | -------- | ------------------------------------------------------ | | COLLOQUIAL_API_TOKEN | Yes | Bearer token for the Colloquial API. | | COLLOQUIAL_ENDPOINT | No | API base URL. Defaults to https://api.colloquial.io. |

Using with Claude Desktop

Go to Settings > Developer > Edit config and add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "colloquial": {
      "command": "npx",
      "args": ["-y", "@colloquial/colloquial-mcp-server@latest"],
      "env": {
        "COLLOQUIAL_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

HTTP transport

In addition to the stdio entrypoint above, the package ships a stateless Streamable HTTP server:

npm run start:http   # serves POST /mcp and GET /health, port from PORT (default 3000)

The standalone HTTP server is single-tenant: like stdio, it authenticates every request with COLLOQUIAL_API_TOKEN from the environment. For multi-tenant hosting, import the app builder and supply your own auth middleware and per-request client provider:

import { createHttpApp } from "@colloquial/colloquial-mcp-server/http";

const app = createHttpApp({ clientProvider, authProvider });

License

MIT