Navin library

The Navin library screen lets you browse the skills, plugins, commands, agents, MCP presets and channels of the Navin library vendored with the platform, activate them for a project, install MCP servers and channels with secret references, start isolated MCP instances, and manage the rules every run of the project receives. Portal path: /studio/navin-library. It is used by developers, application owners and tenant administrators.

What the screen shows

At the top: Project (the projects of GET /v1/projects, chosen by default when there is only one), the badge Library x.y.z and one count per kind (GET /v1/navin-library). Without any project the screen shows No project yet. The tabs Active in the project, MCP instances and Rules show Choose a project first until a project is chosen. The selected tab is kept in the address.

Catalogue

• Kind buttons with their counts: Skills, Plugins, Commands, Agents, MCP presets, Channels.
• Search (name or description) and, for skills, plugins and MCP presets, Category (All categories or one category).
• A table (GET /v1/navin-library/{kind}) with Name, Description, Category, Version and a row menu: Activate in the project (or Already active) for skills, plugins, commands and agents; Install for MCP presets and channels.
• A click on a row opens a side panel (GET /v1/navin-library/{kind}/{name}): description, category, version, digest, the button Activate in the project or Install, then SKILL.md and Files for a skill, README.md and plugin.json for a plugin, Content for a command or an agent, Full contract for an MCP preset or a channel.

Active in the project

Read from GET /v1/projects/{project_id}/navin-library:

• Counts per kind and the library version used.
• Activations: Name, Status, Type, Brought by plugin, Version, Resource, Date, with the row action Remove.
• MCP servers of the project: Name, Status, Preset, URL, with the row action Access, and the button Sync the servers hosted by the Navin Manager.
• Channels of the project: Name, Status, Type, Preset, Agent reference.

MCP

Cards of the MCP presets with their name, transport, description, category, hosting (Hosted by the Navin Manager, Desktop application, Online service: internal address required), the badge Not installable when needed, and Configure. Configure opens the form Install name: Server name (default <name>-<project>), Endpoint URL (optional) or Endpoint URL (required) for a stdio or online preset, Transport (Preset default, streamable_http, sse), Allowed tools (comma separated), then the fields of the preset; a secret field has the badge Reference and takes only an openbao:// or env:// reference.

MCP instances

Read from GET /v1/projects/{project_id}/mcp/instances, refreshed every 3 seconds while an instance is provisioning or terminating:

• A warning The MCP Runtime is not enabled on the platform when the runtime is off.
• Templates: the source of the catalogue (company catalogue on SeaweedFS with its version, or starting templates of the platform), then one card per template with Allowed or Not allowed by the policy, description, image, transport, credentials (No credentials, Personal secret reference, Dynamic database credentials) and Activate.
• Instances: filter Filter by state (All states, Provisioning, Ready, Sleeping, Failed, Terminating, Terminated) and a table Template, Name, Status, Created, Last activity, Expires, End reason, with the row actions Journal, Start, Stop, Destroy. A row click opens the journal.
• Project policy: Allowed templates (none checked means every template), Allowed hosts (host names or *.domain patterns), Allowed database roles, Idle time (seconds) (60 to 86400, default 900), Maximum lifetime (seconds) (300 to 86400, default 28800), Instances per user (1 to 20, default 3), Instances per project (1 to 200, default 20), and Save the policy.
• The Activate name panel: Instance name, Idle time (seconds) within the policy bounds, the parameters of the template (host, host list, name, database role, integer, choice), Secret reference for a template with a personal secret, Allowed agents, Allowed tools (empty means every tool), Cancel and Activate.
• The Journal of name panel: state badge, credentials state, error, end or sleep reason, Template, Generation, Owner, Resource, URL, Allowed agents, Allowed tools, Expires, and Events (event name, date, actor, generation, trace identifier, details).

Channels

A table of the library channels: Name, Fields, Streaming, Official site, with the row action Configure. Configure opens Install the name channel: Channel name, Agent reference (for example agent:support-bot), the fields of the channel contract (text, integer, yes or no, list, choice, secret reference) and Requirements (one alternative of each) as badges.

Rules

• Rules of the project (GET /v1/projects/{project_id}/rules): Name, Mode, Source, Path, Globs, Bytes, Date, with Edit and Delete, and the button New rule.
• Rule editor: Name, Mode (Always, Conditional), Source (navin, cursor, cursor_legacy, cline, windsurf, copilot), Description, Globs, Content, Save the rule.
• Import from a repository: the rule sources the library recognizes, Files and Folder pickers, the relative path of each chosen file (editable), Import and Clear, then the lists Imported and Skipped (not a rule file, empty, too large).
• Prompt preview (GET /v1/projects/{project_id}/rules/prompt): counts Always and Conditional, digest, the prompt section, and Refresh.

Actions

Button or action	What it does	API call	Roles
Project	Chooses the project the tabs work on.	GET /v1/projects	Every signed in user
Kind button, Search, Category	Lists the items of one kind with the filters.	GET /v1/navin-library/{kind}	Every signed in user of the tenant
Click a catalogue row	Opens the item panel.	GET /v1/navin-library/{kind}/{name}	Every signed in user of the tenant
Activate in the project (row menu or panel)	Activates a skill, a plugin (with its skills, commands and agents), a command or an agent.	POST /v1/projects/{project_id}/navin-library/activations	LIBRARY_WRITERS, editor relation on the project
Install (MCP preset or channel row)	Opens the MCP or Channels tab on the item.	None	Everyone
Remove then Confirm	Removes an activation; a plugin takes what it brought.	DELETE /v1/projects/{project_id}/navin-library/activations/{activation_id}	LIBRARY_WRITERS, editor relation on the project
Sync the servers hosted by the Navin Manager	Creates, updates or disables the project servers hosted by the Navin Manager.	POST /v1/mcp/hosted/sync	tenant_admin
Access then Save the access	Sets the users and agents allowed to call the server through the MCP Gateway (empty list: every member of the project).	PUT /v1/mcp/servers/{server_id}/access	LIBRARY_WRITERS
Configure (MCP card) then Install	Installs the MCP preset as a server of the project.	POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install	LIBRARY_WRITERS, editor relation on the project
Activate (template card) then Activate	Starts an isolated MCP instance of yours in the project.	POST /v1/projects/{project_id}/mcp/instances	INSTANCE_WRITERS, editor relation on the project
Filter by state	Lists the instances in one state.	GET /v1/projects/{project_id}/mcp/instances	Viewer relation on the project
Journal or row click	Opens the state and the events of the instance.	GET /v1/projects/{project_id}/mcp/instances/{instance_id}	Viewer relation, owner or tenant administrator
Start	Starts a sleeping or failed instance again (new generation and credentials).	POST /v1/projects/{project_id}/mcp/instances/{instance_id}/start	Owner of the instance or tenant administrator
Stop	Stops a running instance now: it sleeps and its next call recreates it.	POST /v1/projects/{project_id}/mcp/instances/{instance_id}/stop	Owner of the instance or tenant administrator
Destroy then Confirm	Revokes the credentials, deletes the instance and its resources; the journal is kept.	DELETE /v1/projects/{project_id}/mcp/instances/{instance_id}	Owner of the instance or tenant administrator
Save the policy	Saves the MCP Runtime policy of the project.	PUT /v1/projects/{project_id}/mcp/policy	tenant_admin
Configure (channel row) then Install	Creates a channel of the project from the channel contract.	POST /v1/projects/{project_id}/navin-library/channels/{name}/install	LIBRARY_WRITERS, editor relation on the project
New rule	Clears the rule editor.	None	Everyone
Edit or row click	Loads the rule in the editor.	None	Everyone
Save the rule	Creates or replaces the rule of that name.	PUT /v1/projects/{project_id}/rules/{name}	LIBRARY_WRITERS, editor relation on the project
Delete then Confirm	Deletes the rule.	DELETE /v1/projects/{project_id}/rules/{name}	LIBRARY_WRITERS, editor relation on the project
Files, Folder, Clear	Chooses or clears the files to import.	None	Everyone
Import	Imports the chosen rule files (200 files at most).	POST /v1/projects/{project_id}/rules/import	LIBRARY_WRITERS, editor relation on the project
Refresh	Reads the prompt preview again.	GET /v1/projects/{project_id}/rules/prompt	Viewer relation on the project
Cancel, Close	Closes a dialog or a form without saving.	None	Everyone

Roles

• LIBRARY_WRITERS (platform_admin, tenant_admin, developer, application_owner, in portal/src/screens/navin-library.tsx) enables activating, removing, installing, access, saving and importing rules; other users see Read only: activating and installing need the tenant administrator, developer or application owner role. The Control Plane checks WRITE_ROLES (tenant_admin, developer, application_owner, in services/control-plane/src/eai/domains/agents/kit.py) and the editor relation on the project (services/control-plane/src/eai/domains/navin_library/routes.py); platform_admin passes every role check.
• INSTANCE_WRITERS (platform_admin, tenant_admin, developer) enables Activate on a template. The server requires WRITE_ROLES and the editor relation on the project (services/control-plane/src/eai/domains/mcp_runtime/routes.py).
• Journal, Start, Stop and Destroy need the viewer relation on the project; a user sees and acts on their own instances, a tenant administrator on every instance of the project.
• Save the policy and Sync the servers hosted by the Navin Manager are enabled for tenant_admin only, and the server requires tenant_admin.
• Reading the catalogue needs only a signed in user of the tenant; reading the project, the instances and the rules needs the viewer relation on the project.

Typical tasks

Activate a skill for a project

1. Choose the project. Activations belong to a project. Pick it in Project. Expected result: the tabs are no longer empty. If it fails: No project yet means you must create a project first.
2. Find the skill. Open Catalogue, click Skills and type in Search. Expected result: the matching rows. If it fails: change the search or the category.
3. Read it. Click the row to read SKILL.md and Files. Expected result: the side panel. If it fails: click Retry in the panel.
4. Activate. Click Activate in the project. Expected result: the toast Activated: 1 item(s) and the button Already active. If it fails: a disabled button means a missing role or no project.

Install an MCP server from a preset

1. Open the preset. Open MCP and click Configure on the card. Expected result: the form Install name. If it fails: Not installable means the preset cannot be installed.
2. Give the endpoint. A stdio preset runs on a host managed by the Navin Manager and an online server is not allowed: give the internal HTTP address. Fill Endpoint URL. Expected result: no red message. If it fails: the URL must start with http:// or https://.
3. Fill the fields. Put the secret in OpenBao and enter its reference, for example openbao://secret/data/mcp/<name>#token. Expected result: no problem listed. If it fails: a secret field accepts only an openbao:// or env:// reference.
4. Install. Click Install. Expected result: MCP server installed and the server in Active in the project. If it fails: see Troubleshooting.
5. Restrict the access. On Active in the project, use Access on the server, list the principals and click Save the access. Expected result: Access saved. If it fails: a server of an MCP instance has its access managed by the instance.

Start an isolated MCP instance

1. Check the policy. The template must be allowed. Open MCP instances and read the badge of the card. Expected result: Allowed. If it fails: a tenant administrator checks the template in Allowed templates and clicks Save the policy.
2. Activate. Click Activate, fill the parameters, the Secret reference when asked and Allowed agents. Expected result: no problem listed. If it fails: a host outside Allowed hosts is refused.
3. Start. Click Activate in the panel. Expected result: Instance provisioning, then the status Ready. If it fails: open Journal and read the failure reason.
4. Destroy at the end. Click Destroy then Confirm. Expected result: Instance destroyed, the journal kept. If it fails: an instance already terminating cannot be destroyed again.

Import the rules of a repository

1. Choose the files. Click Folder and select the repository. Expected result: one line per file with its relative path. If it fails: more than 200 files show At most 200 files per import.
2. Check the paths. The path decides how a file is read (for example .cursor/rules/style.mdc). Fix any path. Expected result: correct paths. If it fails: click Clear and start again.
3. Import. Click Import. Expected result: Imported: n rule(s) and the lists Imported and Skipped. If it fails: a skipped file is not a rule file, empty or too large.
4. Read the prompt. Click Refresh in Prompt preview. Expected result: the section every run of the project receives. If it fails: Empty prompt means no rule is saved.

danger

Never type a secret value in a field of a preset, a template or a channel. Only openbao:// or env:// references are accepted; the server refuses any other value.

Troubleshooting

Symptom	Cause	Fix
Choose a project first	No project is chosen.	Pick one in Project.
Error navin_library_unavailable (503)	The vendored library cannot be read.	Check the installation of the Control Plane.
Error navin_skill_name_taken (409)	A skill of the same name already exists in the tenant.	Remove or rename the existing skill.
Error mcp_preset_not_installable (409)	The preset cannot be installed.	Choose another preset.
Error mcp_preset_needs_endpoint (409)	A stdio preset needs the HTTP endpoint that exposes it.	Fill Endpoint URL (required).
Error mcp_preset_secret_ref_required or channel_secret_ref_required (422)	A secret field holds a value instead of a reference.	Enter an openbao:// or env:// reference.
Error channel_field_missing (422)	A requirement of the channel is not met.	Fill one alternative of each amber requirement.
Error mcp_instance_access_managed (409) on Save the access	The server belongs to an MCP instance.	Set Allowed agents on the instance instead.
Error mcp_project_forbidden (403) on sync	The requested project differs from the project of the request.	Run the sync from the right project.
The MCP Runtime is not enabled on the platform or mcp_runtime_disabled (409)	The runtime is off.	The operator sets EAI_MCP_RUNTIME_ENABLED and installs the ToolHive Operator.
Error mcp_template_not_allowed or mcp_host_not_allowed (403)	The project policy forbids the template or the host.	Ask the tenant administrator to change the policy.
Error mcp_instance_quota (409)	The instance quota per user or per project is reached.	Destroy an instance or raise the quota in the policy.
Error mcp_instance_exists (409)	An instance of that name already exists.	Choose another Instance name.
Error mcp_credential_required (422)	The template needs a personal secret reference.	Fill Secret reference.
Error mcp_instance_busy (409)	An operation is still running on the instance.	Wait for the end of the operation, then retry.
Error rule_scope_required (422)	A conditional rule has neither globs nor description.	Add globs or a description.
Error forbidden (403) with required_roles	A role is missing.	Ask for the developer or application_owner role.

Related pages

• Navin library guide
• MCP development
• Skill development
• MCP studio
• MCP servers
• Channels
• Projects