Connect an AI client to Usable

Usable's Model Context Protocol server lets an AI client search, read, create, update, and organize knowledge in workspaces you can access. The production endpoint is:

https://usable.dev/api/mcp

Use the remote Streamable HTTP transport. For clients that support remote MCP OAuth, prefer the OAuth 2.1 browser flow with PKCE instead of creating and pasting a personal access token.

Connect from the dashboard

1. Sign in to Usable.
2. Select Connect MCP on the dashboard, or open the connection dialog from a workspace page.
3. Copy the remote MCP URL or the snippet for your client.
4. Add the server to the client.
5. Complete the browser sign-in and approve the requested access.
6. List the available tools.
7. Run a read-only workspace or search call before enabling write workflows.

The dialog can preselect a workspace when opened from that workspace, but a connection never bypasses workspace permissions.

Claude Code

The released connection dialog uses:

claude mcp add --transport http usable https://usable.dev/api/mcp
claude mcp list

Then run /mcp in Claude Code and choose Authenticate. Complete the Usable sign-in in the browser and return to the client.

Claude Desktop

In Claude Desktop, add a custom connector:

Name: Usable
MCP server URL: https://usable.dev/api/mcp

Approve the browser sign-in when prompted. Exact navigation labels can change between client releases; use the current Connectors or MCP settings surface.

Codex

The released configuration pattern is:

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

Then authenticate:

codex mcp login usable

OpenCode and other clients

The released OpenCode-style configuration is:

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

For another compatible client, use:

• URL: https://usable.dev/api/mcp
• transport: Streamable HTTP;
• OAuth discovery: /.well-known/oauth-protected-resource;
• authentication: OAuth 2.1 with PKCE browser sign-in.

Use the client's current documentation for where remote MCP servers are configured. Do not copy a configuration format from one client into another.

Clients without OAuth support

A client or server-side automation that cannot complete the browser flow can use a dedicated personal access token when supported:

Authorization: Bearer <personal-access-token>

Create one token per client, scope it to only the required workspaces and actions, store it in the client's secret store or server environment, and revoke it when the integration is retired. See Personal access tokens.

Never put a token in a memory fragment, source repository, prompt, screenshot, or public support message.

Verify the connection

First inspect the tool inventory. Your client normally does this through tools/list. The returned list is the source of truth for tools visible to that connection; a short list shown in the dashboard is only an overview.

Then ask the client to:

1. call list-workspaces;
2. identify one workspace you expect to read;
3. call agentic-search-fragments with that workspace scope;
4. fetch one result with get-memory-fragment-content;
5. report the fragment title without changing anything.

This verifies transport, authentication, workspace visibility, search, and full-content retrieval without authorizing a mutation.

Security boundary

An MCP connection acts with the signed-in user's effective access or the token's narrower scope. OAuth approval, possession of a workspace ID, and tool visibility do not grant additional roles.

Use a read-only connection for clients that only answer questions. Add create or update access only when the client has a reviewed write workflow and a human approval boundary.

Troubleshooting

Browser authentication does not open

Confirm the client supports remote MCP OAuth and that it is using Streamable HTTP. Re-add the server from the current connection dialog.

The server connects but no tools appear

Confirm the URL has no stale host or extra path. Reauthenticate, then inspect the raw tools/list result if the client exposes it.

A workspace is missing

Check the signed-in account, workspace membership or public subscription, and token workspace scope. Use list-workspaces; do not guess workspace IDs.

The client requires a token

Use a dedicated, least-privilege PAT rather than a browser session value. Never extract cookies or session tokens from the dashboard.

Next step

Read MCP tools and permissions before enabling additional capabilities.