Organize knowledge through MCP

Usable MCP can do more than search fragments. Authorized agents can help choose a workspace, create or update workspaces, organize fragments into collections, link knowledge across workspace boundaries, and hand off file or application workflows.

Keep organization intentional. A model should not create containers or relationships merely because the tools are available.

Start with accessible workspaces

Call list-workspaces to discover the current connection's workspaces and roles. Use stable workspace IDs for later calls, but show names to users when asking them to choose a target.

Do not route a mutation from a workspace name alone. Similar names can exist, and a client may see private, organization, and subscribed public workspaces together.

Create or update a workspace

create-workspace and update-workspace require the relevant account, owner, or administrative capability. Before creating one, confirm:

purpose and audience;
private or public visibility;
organization relationship;
whether Hosted Zone placement is required;
who will own and maintain it.

In v1.198.1, create-workspace can accept a Hosted Zone ID for eligible Pro organization owners or administrators. Placement introduces Cloud and Leaf routing rules; see Hosted Zones and MCP troubleshooting.

Treat visibility changes as high impact and require explicit approval.

Select a fragment type

Call get-fragment-types for each target workspace. Types are workspace-defined, so a type ID from one workspace is not portable to another.

Choose a type by its current name and description. New workspaces normally include Knowledge and Skill, but do not assume every older or customized workspace has the same defaults.

Discover public workspaces

Use search-public-workspaces to find public workspaces, then subscribe-to-workspace when the user wants read-style access.

A subscription makes accessible public knowledge easier to list and search. It does not grant writing or administration. Confirm the workspace identity and description before subscribing on the user's behalf.

Use collections for curated groups

Collections group related fragments within one workspace. Use:

list-collections to inspect existing groups;
get-collection to verify details and contents;
create-collection for a reviewed new group;
update-collection to maintain its name or description.

Create a collection when the grouping has a durable purpose for humans or agents, not for every one-off search.

MCP fragment tools commonly manage membership through collectionIds. Fetch the current fragment and collection before replacing membership so unrelated collections are not removed accidentally.

Use symlinks deliberately

create-fragment-symlink and remove-fragment-symlink support manual cross-workspace sharing or relationships where permissions allow.

Before creating a link:

Verify the source and target workspaces.
Confirm the content is appropriate for the target audience.
Check for an existing link.
Explain that the linked material remains maintained from its source context.
Verify the resulting relationship.

Do not link private operational content into a public or broad workspace. Tags or automation rules can route more content than intended, so broad symlink automation belongs in an owner-reviewed dashboard or deterministic workflow.

Hand off file workflows

The MCP file tool family can request an upload flow, search file metadata, get an authorized file reference, and attach a file to a fragment.

File uploads can be asynchronous and client support varies. Direct multipart REST is often better for deterministic imports. Hosted Zone V1 does not support file payload workflows on Leaf workspaces.

Detailed file guidance belongs in the Assets & files section. Until then, never treat a file ID as proof of ownership or readiness.

Application management

manage-application is capability-dependent and intended for authorized application records and marketplace workflows. Keep it out of ordinary knowledge agents. Inspect its current tool schema and require explicit confirmation for changes involving credentials, redirects, grants, or publication.

Safe organization policy

List before creating.
Resolve exact IDs before mutating.
Show the user the target and effect.
Keep public subscription read-only.
Require approval for visibility, placement, symlinks, and application changes.
Refetch after each mutation.
Use REST for deterministic bulk membership or file operations.

Troubleshooting

A type or collection cannot be found

Verify that its ID belongs to the target workspace and that the connection can read it.

A subscriber cannot add content

That is expected. Subscriber access is read-style; request a suitable workspace role only when needed.

A symlink is rejected

Check source and target access, existing relationships, visibility, and whether the operation would create an unsafe or cyclic route.

File tools are unavailable

Check client upload support, permissions, processing state, and whether the workspace is Leaf-backed.

Keep organization intentional. A model should not create containers or relationships merely because the tools are available.

Start with accessible workspaces

Call list-workspaces to discover the current connection's workspaces and roles. Use stable workspace IDs for later calls, but show names to users when asking them to choose a target.

Do not route a mutation from a workspace name alone. Similar names can exist, and a client may see private, organization, and subscribed public workspaces together.

Create or update a workspace

create-workspace and update-workspace require the relevant account, owner, or administrative capability. Before creating one, confirm:

purpose and audience;
private or public visibility;
organization relationship;
whether Hosted Zone placement is required;
who will own and maintain it.

Treat visibility changes as high impact and require explicit approval.

Select a fragment type

Call get-fragment-types for each target workspace. Types are workspace-defined, so a type ID from one workspace is not portable to another.

Choose a type by its current name and description. New workspaces normally include Knowledge and Skill, but do not assume every older or customized workspace has the same defaults.

Discover public workspaces

Use search-public-workspaces to find public workspaces, then subscribe-to-workspace when the user wants read-style access.

Use collections for curated groups

Collections group related fragments within one workspace. Use:

list-collections to inspect existing groups;
get-collection to verify details and contents;
create-collection for a reviewed new group;
update-collection to maintain its name or description.

Create a collection when the grouping has a durable purpose for humans or agents, not for every one-off search.

MCP fragment tools commonly manage membership through collectionIds. Fetch the current fragment and collection before replacing membership so unrelated collections are not removed accidentally.

Use symlinks deliberately

create-fragment-symlink and remove-fragment-symlink support manual cross-workspace sharing or relationships where permissions allow.

Before creating a link:

Verify the source and target workspaces.
Confirm the content is appropriate for the target audience.
Check for an existing link.
Explain that the linked material remains maintained from its source context.
Verify the resulting relationship.

Hand off file workflows

The MCP file tool family can request an upload flow, search file metadata, get an authorized file reference, and attach a file to a fragment.

File uploads can be asynchronous and client support varies. Direct multipart REST is often better for deterministic imports. Hosted Zone V1 does not support file payload workflows on Leaf workspaces.

Detailed file guidance belongs in the Assets & files section. Until then, never treat a file ID as proof of ownership or readiness.

Application management

Safe organization policy

List before creating.
Resolve exact IDs before mutating.
Show the user the target and effect.
Keep public subscription read-only.
Require approval for visibility, placement, symlinks, and application changes.
Refetch after each mutation.
Use REST for deterministic bulk membership or file operations.

Troubleshooting

A type or collection cannot be found

Verify that its ID belongs to the target workspace and that the connection can read it.

A subscriber cannot add content

That is expected. Subscriber access is read-style; request a suitable workspace role only when needed.

A symlink is rejected

Check source and target access, existing relationships, visibility, and whether the operation would create an unsafe or cyclic route.

File tools are unavailable

Check client upload support, permissions, processing state, and whether the workspace is Leaf-backed.

Start with accessible workspaces

Create or update a workspace

Select a fragment type

Discover public workspaces

Use collections for curated groups

Use symlinks deliberately

Hand off file workflows

Application management

Safe organization policy

Troubleshooting

A type or collection cannot be found

A subscriber cannot add content

A symlink is rejected

File tools are unavailable

Related pages

Start with accessible workspaces

Create or update a workspace

Select a fragment type

Discover public workspaces

Use collections for curated groups

Use symlinks deliberately

Hand off file workflows

Application management

Safe organization policy

Troubleshooting

A type or collection cannot be found

A subscriber cannot add content

A symlink is rejected

File tools are unavailable

Related pages