knot.mcp_server
The knot.mcp_server library manages remote MCP servers: other MCP servers, reached over HTTP(S) or started as a stdio command, whose tools knot exposes to the user who added them under the server’s namespace. Calling those tools is knot.mcp’s job; this library manages the server records. Creating, changing and deleting servers needs the Manage MCP Servers permission.
Execution Environment
| Environment | Behaviour |
|---|---|
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) |
Available; authenticated automatically via the Go-provided knot.apiclient transport. |
| Health check scripts | Only when the space’s environment sets KNOT_API_PORT or KNOT_URL/KNOT_TOKEN: there is no built-in transport, so the Python knot.apiclient configures itself from the agent (as the space owner) or those variables, and calls raise otherwise. See Environment Compatibility. |
| External (standalone scripts) | Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables). |
Functions
| Function | Description |
|---|---|
list(user_id=None) |
List remote MCP servers |
get(namespace_or_id) |
Get a server, without its token values |
create(namespace, url="", command="", ...) |
Add a server; returns its ID |
update(namespace_or_id, ...) |
Update a server; only the arguments given change |
delete(namespace_or_id) |
Delete a server |
tools(namespace_or_id) |
Connect to a server and list its tools |
set_tool_enabled(namespace_or_id, tool_name, enabled) |
Switch one of a server’s tools on or off |
protocol_version(namespace_or_id) |
The MCP protocol version negotiated with a server |
Servers are found by namespace (among your own) or ID.
list(user_id=None)
List remote MCP servers, sorted by namespace.
Parameters:
user_id(string, optional): List another user’s servers (needs Manage MCP Servers). Default: your own.
Returns: list of dicts, each containing:
id(string),user_id(string)namespace(string): Prefix the server’s tools are exposed underurl(string): HTTP(S) endpoint, empty for a stdio servercommand(string),args(list),env(list of"KEY=value"): How a stdio server is startedenabled(bool): Whether knot connects to the servertool_visibility(string):"native"(tools listed in tools/list) or"discoverable"(found only through tool_search)disabled_tools(list): Tool names switched offremote_search(bool): Whether tool_search queries are forwarded to the server
get(namespace_or_id)
Get a remote MCP server. Token values are never returned.
Returns: dict - The fields list() returns, plus auth_type ("", "bearer" or "oauth2"), has_token, oauth_client_id, oauth_token_url and has_oauth_tokens.
create(namespace, url="", command="", args=None, env=None, auth_type="", token="", oauth_client_id="", oauth_token_url="", oauth_access_token="", oauth_refresh_token="", enabled=True, tool_visibility=“native”, remote_search=False)
Add a remote MCP server for the current user. Give url for an HTTP(S) server, or command (with args and env) for a stdio server.
Parameters:
namespace(string): Prefix for the server’s tools; unique among your servers and must not contain__url(string): HTTP(S) endpointcommand(string),args(list),env(list of"KEY=value"): stdio serverauth_type(string):""(none),"bearer"(withtoken) or"oauth2"(with theoauth_*arguments)enabled(bool): Whether knot connects to the server (defaultTrue)tool_visibility(string):"native"(default) or"discoverable"remote_search(bool): Forward tool_search queries to the server
Returns: string - The new server’s ID. Raises if neither url nor command is given, or the namespace is taken or invalid.
update(namespace_or_id, namespace=None, url=None, command=None, args=None, env=None, auth_type=None, token=None, oauth_client_id=None, oauth_token_url=None, oauth_access_token=None, oauth_refresh_token=None, enabled=None, tool_visibility=None, remote_search=None)
Update a remote MCP server. Only the arguments given change — namespace renames it — and stored tokens are kept unless new ones are given.
Returns: bool - True on success
delete(namespace_or_id)
Returns: bool - True on success
tools(namespace_or_id)
Connect to the server now and list its tools.
Returns: list of dicts with name (without the namespace prefix), description, enabled and is_app (an MCP Apps tool, with a linked ui:// resource). Raises with the reason when the server cannot be reached.
set_tool_enabled(namespace_or_id, tool_name, enabled)
Switch one of the server’s tools on or off; a tool switched off is not offered.
Returns: bool - True on success
protocol_version(namespace_or_id)
Returns: string - The MCP protocol version negotiated with the server, e.g. "2025-06-18"; empty when it cannot be reached.
Examples
import knot.mcp_server as mcp_server
mcp_server.create("github", url="https://api.githubcopilot.com/mcp/",
auth_type="bearer", token="ghp_...")
for tool in mcp_server.tools("github"):
if tool["name"].startswith("delete_"):
mcp_server.set_tool_enabled("github", tool["name"], False)