Usable MCP server

Endpoint: https://usable.dev/api/mcp
Protocol: Model Context Protocol over HTTP (JSON-RPC 2.0)
Server name: usable-knowledge-base
MCP protocol version: 2025-03-26

The Usable MCP server lets AI clients search, read, create, update, and organize Usable workspace knowledge. It is the preferred interface when an AI assistant needs durable team memory, workspace-aware lookup, or controlled write access to fragments.

When to use MCP instead of REST

Use MCP when:

• An AI assistant should choose which fragments to search or fetch.
• You want a model to create or update knowledge in a workspace with tool-level permissions.
• You need a client such as Claude Desktop, Cursor, VS Code MCP, Copilot Studio, ChatGPT Apps, or a custom MCP client to access Usable knowledge.

Use REST when:

• You are building deterministic service-to-service imports, exports, sync jobs, or webhooks.
• You need multipart file upload from a script.
• You need a stable endpoint for a specific operation rather than model-driven tool selection.

Connecting

OAuth 2.1 (recommended)

The dashboard MCP connect dialog starts with the remote MCP URL:

https://usable.dev/api/mcp

Client examples:

# Claude Code
claude mcp add --transport http usable https://usable.dev/api/mcp
claude mcp list
# In Claude Code, run /mcp and choose Authenticate

# Codex (opencode.toml)
[mcp_servers.usable]
url = "https://usable.dev/api/mcp"
# Then run: codex mcp login usable

// Generic Streamable HTTP
{
  "mcp": {
    "usable": {
      "type": "remote",
      "url": "https://usable.dev/api/mcp",
      "enabled": true
    }
  }
}

Bearer token

For non-OAuth clients, use a personal access token:

Authorization: Bearer <personal-access-token>

Recommended token practice:

1. Create a dedicated token per AI client or automation.
2. Scope the token to only the workspaces the client needs.
3. Give read-only permissions for search/fetch clients.
4. Add create/update permissions only for clients that are allowed to write.
5. Revoke tokens immediately when a client is retired or compromised.
6. Never store token values in memory fragments or public docs.

Transport basics

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

List tools

curl https://usable.dev/api/mcp \
  -H "Authorization: Bearer <personal-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Tool inventory

The standard Usable MCP tool set contains 23 tools.

Discovery and search

Fragment management

Workspace management

Collections

Files

Applications

OpenAI-compatible mode

Use https://usable.dev/api/mcp?openai=true for clients expecting OpenAI-style search and fetch aliases.

Recommended search workflow

1. Start with agentic-search-fragments.
2. Include workspace scope when known.
3. Include tags such as repo:<name>, docs, public, or release tags.
4. Rerun search when scope changes or results are insufficient.
5. Use get-memory-fragment-content for every fragment you rely on.

Example:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "agentic-search-fragments",
    "arguments": {
      "query": "REST API authentication and token permissions",
      "workspaceId": "YOUR_WORKSPACE_ID",
      "tags": ["docs", "api"],
      "limit": 10
    }
  }
}

Fragment authoring through MCP

{
  "jsonrpc": "2.0",
  "id": 20,
  "method": "tools/call",
  "params": {
    "name": "create-memory-fragment",
    "arguments": {
      "workspaceId": "YOUR_WORKSPACE_ID",
      "title": "MCP setup for public docs",
      "content": "# MCP setup\n\nConnect using /api/mcp...",
      "summary": "How to connect an MCP client to Usable.",
      "tags": ["docs", "public", "mcp"]
    }
  }
}

Permissions by workflow

Troubleshooting

tools/list returns 401

Check that the Authorization: Bearer <token> header is present and the token is valid.

A tool returns 403

The token lacks permission for the workspace or action. Check workspace membership, token scope, and tool permission requirements.

create-memory-fragment returns isError: true

Since v1.192.1, fragment-type problems are reported as tool-level results. Typical causes:

• You passed a fragmentTypeId that does not exist in the target workspace.
• The workspace has no usable default fragment type.

Fix: call get-fragment-types for the same workspaceId, then pass a valid fragmentTypeId explicitly.

Search returns no useful fragments

Broaden the query, add or remove tags, specify the correct workspace, and rerun agentic-search-fragments. Use list-workspaces to verify the client can see the target workspace.

The assistant cites a fragment from search but did not read it

Require the assistant to call get-memory-fragment-content before relying on a result. Search snippets are not a substitute for full source content.