MCP

The Model Context Protocol (MCP) server can be enabled on the knot server by adding the following configuration to the knot.toml file:

[server.mcp]
enabled = true

This configuration enables the MCP server at the path /mcp. Notably, it does not require knot to have access to a Large Language Model (LLM).

Connecting a Client

The knot MCP server operates over HTTP transport and is accessible at the URL: https://<your-knot-domain.com>/mcp

For example, if your knot installation is hosted at knot.getknot.dev, the MCP server URL would be: https://knot.getknot.dev/mcp

OAuth2-Supported Clients

If your client supports OAuth2, it will connect to the MCP server and allow you to log in using your standard credentials. During this process, an API token will be generated for use.

Non-OAuth2 Clients

For clients that do not support OAuth2, you will need to manually generate a new API token via the web interface and provide it to the MCP client. Use the following format:

In both cases, the MCP client will have the same level of access to tools as the user who generated the API token.

Tool Modes

Knot’s MCP server supports two different tool modes, configured via the mcp_mode setting in your knot.toml:

Tool Discovery Mode (Default)

In tool discovery mode, tools are discovered on-demand to minimize context usage. This is efficient for AI assistants that need to manage their token usage.

Workflow:

1. Use tool_search(query="<operation>") to find the appropriate tool
2. Use execute_tool(name="<tool_name>", arguments={...}) to execute the tool

Example:

tool_search("list spaces") → Returns tool information
execute_tool("list_spaces", {}) → Executes the tool

Benefits:

• Dynamic tool availability based on user permissions
• Reduced memory footprint and context usage
• Permission-based filtering
• Request-scoped authentication

Native Tools Mode

In native tools mode, all tools are pre-loaded and directly available without discovery. This is simpler for clients that don’t support the discovery pattern.

Configuration:

[server.mcp]
enabled = true
native_tools = true

Workflow:

• All tools are available directly in the tool list
• Use tools by name with their required arguments
• No discovery pattern needed

Example:

list_spaces() → Direct tool call
create_space({...}) → Direct tool call

Tools

The following tools are available on the MCP server. The specific tools and operations accessible depend on the user’s permissions:

Space Management

• list_spaces: List all spaces for the current user, including status and sharing details.
• get_space: Retrieve detailed space information, including configuration and status.
• create_space: Create a new development space.
• update_space: Update an existing space.
• delete_space: Permanently delete a space and all its data.
• start_space: Start a space.
• stop_space: Stop a space.
• restart_space: Restart a space.
• share_space: Share a space with another user.
• stop_sharing_space: Stop sharing a space.
• transfer_space: Transfer ownership of a space to another user.

Template Management

• list_templates: List all space templates.
• create_template: Create a new space template.
• update_template: Update an existing template.
• get_template: Retrieve detailed template information, including configuration and job specifications.
• delete_template: Permanently delete a template.

File Operations

• read_file: Read the contents of a file from a running space.
• write_file: Write content to a file in a running space.

Command Execution

• run_command: Execute a command in a running space and return the results.

User and Group Management

• list_users: List details of all users (e.g., ID, username, email, active status, groups).
• list_groups: List all user groups.

Icons and Skills

• list_icons: List all available icons with descriptions and URLs.
• skills: Access the knowledge base for guides and best practices. Call without a filename to list all skills, or with a filename for specific content.