Help & Documentation

Getting started guide, MCP setup, and the interactive API reference.

Getting Started with Usable

Usable is your team's shared memory. Follow these four steps to capture knowledge and recall it across your tools and IDE.

Create a workspace

Sign in and create a workspace for your team or project, then invite teammates any time. From the dashboard you manage fragment types, visibility, and member permissions.

Connect your IDE

Add the remote MCP URL to your client and sign in with OAuth 2.1. Jump to MCP setup for connector snippets. MCP setup

Create your first fragment

Document a library, capture a decision, or record a troubleshooting fix. Pick the right type so search ranks it well later.

Search your knowledge

Ask your LLM to implement based on your fragments. Agentic search finds the right docs and links related fragments automatically.

Common use cases

An engineer documents an internal library; a teammate then asks the LLM to use it and gets a first-try implementation that is itself documented and linked back. DevOps captures CRDs and best practices so the assistant applies secure defaults when provisioning. Teams teach their stack and patterns once, and new hires scaffold code that already matches house style.

Model Context Protocol (MCP)

Connect your IDE or LLM to Usable over remote MCP. The recommended path is the Streamable HTTP URL with OAuth 2.1 browser sign-in.

Add the server URL below to your MCP client. Usable publishes OAuth discovery metadata, so compliant clients open a browser login and complete PKCE automatically.

Recommended MCP URL

https://usable.dev/api/mcp

Codex configuration

[mcp_servers.usable]
url = "https://usable.dev/api/mcp"

# Then run:
codex mcp login usable

OpenCode configuration

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

Claude Desktop users can add a custom connector with the same URL. Claude Code users can run claude mcp add --transport http usable https://usable.dev/api/mcp and then authenticate from /mcp.

Authentication

OAuth 2.1

Browser sign-in with PKCE through Usable's OAuth discovery endpoints.

Remote MCP

No local stdio proxy is needed for connector setup.

Tool reference

Every tool accepts an outputFormat of text or json, and returns JSON-RPC 2.0 content.

agentic-search-fragments

Agentic search with iterative expansion and intelligent selection.

search-memory-fragments

Semantic vector search across workspaces with optional filters.

get-fragment-content

Retrieve the full content and metadata for a single fragment.

create-fragment

Create a fragment with optional summary, tags, and type.

update-fragment

Update fields on an existing fragment; supports selective updates.

list-workspaces

List the workspaces you have access to, with your role in each.

get-fragment-types

Fetch the available fragment types for a workspace.

Workspace-specific setup

For a guided walkthrough with workspace-specific system prompts and fragment types, open Connect MCP inside any workspace in the app.

API Reference

The full reference is an interactive OpenAPI viewer served from /api/docs. Try requests live, browse schemas, and download the spec. A representative slice of endpoints is listed below.

Representative endpoints

GET/api/docsGet the complete OpenAPI 3.0 specification

GET/api/healthAPI health check

GET/api/profile/analyticsGet user analytics for the profile page

GET/api/workspaces/{id}/mcp-system-promptGenerate a workspace MCP system prompt

GET/api/tokens/{id}/analyticsGet token usage analytics

POST/api/ai/embeddingsGenerate text embeddings

Authentication

All requests authenticate with a bearer token in the Authorization header. Create and scope tokens from your account, then keep them out of source control.

curl https://usable.dev/api/health \
  -H "Authorization: Bearer your-access-token"

Manage your tokens

Create, scope, and revoke tokens under Account - API Tokens. Each token can be limited to specific permissions like fragments.read.

Interactive OpenAPI

Open the dedicated API reference to browse schemas, download the OpenAPI document, and test requests. The raw OpenAPI JSON remains available at /api/docs.

Open API reference