MCP tools and permissions

The Usable MCP server exposes tools for knowledge discovery, fragment maintenance, workspace organization, files, and authorized application management. The released v1.198.1 standard inventory contains 23 tools, but the tools and operations available to a particular connection depend on its identity, workspace access, and granted permissions.

Always inspect tools/list at runtime. Documentation describes the released family; the server response describes the current connection.

Tool groups

Discovery and retrieval

• agentic-search-fragments — primary intelligent discovery across accessible fragments;
• search-memory-fragments — semantic search fallback;
• list-memory-fragments — structured filtering and pagination;
• get-memory-fragment-content — complete fragment content and metadata.

Use the search tools to identify candidates, then fetch every source the agent relies on.

Fragment management

• create-memory-fragment;
• update-memory-fragment;
• create-fragment-symlink;
• remove-fragment-symlink.

These require write permissions appropriate to the workspace and operation. A read-only agent should not receive them.

Workspaces and public discovery

• list-workspaces;
• get-fragment-types;
• create-workspace;
• update-workspace;
• search-public-workspaces;
• subscribe-to-workspace.

Subscribing to a public workspace grants read-style access. It does not grant fragment creation, workspace administration, or member management.

Collections

• create-collection;
• get-collection;
• list-collections;
• update-collection.

Collection membership is commonly supplied through collectionIds when creating or updating a fragment.

Files

• request-upload-url;
• search-files;
• get-file;
• attach-file-to-fragment.

File transfer depends on client support, workspace file permissions, processing state, and workspace placement. Hosted Zone V1 does not support file payload workflows on Leaf workspaces.

Applications

manage-application supports authorized application-management actions exposed by its current schema. Do not grant it to a general retrieval agent.

How effective access is calculated

A successful action requires all relevant boundaries to allow it:

1. The credential or OAuth session is valid.
2. The identity can access the workspace.
3. The role allows the operation.
4. The token or grant includes the necessary capability.
5. The object belongs to the expected workspace and is active where required.
6. The selected tool route supports the operation.

A tool can appear in tools/list and still return a permission error for a particular workspace or object. Tool visibility is not authorization.

Read and write profiles

For a question-answering client, grant only workspace and fragment read access. It normally needs list-workspaces, search, list, and full-fragment retrieval.

For a knowledge-maintenance client, add only the specific create/update capabilities and target workspaces it needs. Keep workspace creation, application management, files, and cross-workspace symlinks separate unless the workflow explicitly requires them.

Use separate credentials for separate responsibilities. This makes revocation, auditing, and incident containment clearer.

OpenAI-compatible mode

Clients that expect a search/fetch retrieval contract can connect to:

https://usable.dev/api/mcp?openai=true

That mode adds compatible search and fetch aliases. It does not make a connection more privileged. Use the standard endpoint for full Usable operations.

If a client UI shows only the aliases, compare its filtered display with the raw tools/list response before concluding that the standard tools are absent.

MCP or REST?

Use MCP when a model should choose which sources or tools to call and when a client natively supports the protocol.

Use REST when the operation is deterministic, including imports, exports, synchronization jobs, webhooks, bulk processing, or direct multipart file upload. A fixed service job should not need a model to choose a tool it already knows it must call.

For either interface, enforce authorization on the server and make retries idempotent.

Permission failures

• 401: the credential is missing, expired, malformed, or revoked.
• 403: authentication succeeded, but the user, role, token, or workspace does not allow the action.
• 404: the object may not exist or may be hidden by the access boundary.
• Tool-level error: the JSON-RPC call completed, but the domain action failed; inspect result.isError and its text.

Do not broaden a token automatically after an error. Confirm which operation is required and grant the minimum capability deliberately.

Related pages

• Connect an AI client to Usable
• Search and ground agent answers
• Create and maintain knowledge safely
• Workspace roles and permissions