This MCP server exposes one persistent, in-process IPython namespace with tools to run Python, manage the namespace, inspect and call live objects, and register custom tools—though the supplied schema still contains the F-004 runtime_status tool and runtime metadata that the README says were removed in F-005.
Execute Python expressions, statements, definitions, and multiline blocks in a persistent namespace, with bounded stdout, stderr, display data, final values, execution counts, and structured errors.
List currently available callables with signatures, modules, and docs; search visible objects by exact or partial name.
Call live callables by name using JSON keyword arguments and get JSON-compatible results.
Inspect a live object's kind, type, signature, module, docs, and safe representation with truncation flags.
Reload named modules and refresh shell bindings.
Remove or reset unprotected top-level user names while protecting IPython bindings and configured module aliases.
Register and unregster dynamic tools from supported top-level synchronous callables, with schema fingerprints and revision tracking.
Per the schema only: runtime_status reports worker/queue/epoch/recovery metadata, but the README explicitly says this was removed in F-005 and response models no longer include runtime/epoch metadata.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ipython-mcp Write and execute a Python function to check if a number is prime, then test it on 17."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ipython-mcp exposes one persistent, trusted local IPython namespace through
FastMCP. Variables, functions, classes, imports, module state, and explicitly
registered dynamic tools survive across calls until the server lifespan ends.
The FastMCP server directly owns exactly one in-process IPython
InteractiveShell. Every fixed tool, dynamic-tool lookup, and dynamic call is
serialized through one in-process boundary and works with the same live Python
objects. There is no runtime child process or object-encoding protocol.
This is intentionally not a sandbox. User Python has the server process's permissions. Once a call starts executing Python it runs until it returns or raises. A tool timeout or MCP cancellation cannot safely terminate that code or promise that the shell remains reusable; non-cooperative code can block the trusted local server and requires restarting it.
From a source checkout:
uv sync --extra dev
uv run ipython-mcpFrom a built wheel:
uv build
uv tool install dist/ipython_mcp-0.1.0-py3-none-any.whl
ipython-mcpThe console entry point uses stdio. It writes no non-protocol data to stdout; optional operational logs go to stderr and contain metadata only.
Register a source checkout with Codex (replace the path):
codex mcp add ipython -- \
uv run --directory /absolute/path/to/ipython-mcp ipython-mcpFor a wheel installed with uv tool install:
codex mcp add ipython -- ipython-mcpRelated MCP server: repl-mcp
The server publishes ten stable tools. Registered callables are additional, opt-in tools and are never published automatically.
list returns visible callables with bounded signatures, modules, and docs.
execute runs expressions, statements, definitions, and multiline blocks;
it returns bounded stdout, stderr, display data, final values, and structured
failures.
call_function resolves a live callable without eval, binds a JSON object
as keyword arguments, and returns a JSON-compatible value.
search finds visible objects by exact or partial name with bounded metadata.
reload explicitly reloads named modules and refreshes shell bindings.
inspect returns one object's kind, type, signature, module, docs, and safe
representation with field-level truncation flags.
remove partitions unique top-level names into removed, refused, and
unknown while protecting IPython and configured module bindings.
reset removes unprotected user names, restores configured bindings, clears
dynamic registrations, and preserves the monotonic execution count.
register_tool explicitly publishes one supported top-level synchronous
callable with a deterministic JSON schema and fingerprint.
unregister_tool idempotently removes requested dynamic registrations.
All ten paths use the same shell and registry. Live Python objects never cross a process boundary and response models no longer contain request, queue, worker, recovery, or epoch metadata.
A server can prepare one named uv environment before constructing IPython. The environment lives under an explicit workspace outside the project. It is created without system site packages using the same Python major/minor as the server, or safely reused only when its recorded Python and canonical requirements fingerprint match.
Both IPYTHON_MCP_ENVIRONMENT_WORKSPACE and
IPYTHON_MCP_ACTIVE_ENVIRONMENT are required to enable provisioning. When
both are omitted, uv is never called and the ordinary in-process startup path
is unchanged. Environment variables, trusted library paths, and preloads may
still be used without a uv environment.
Example:
codex mcp add ipython \
--env IPYTHON_MCP_ENVIRONMENT_WORKSPACE=/absolute/task-environments \
--env IPYTHON_MCP_ACTIVE_ENVIRONMENT=analytics-v1 \
--env 'IPYTHON_MCP_ENVIRONMENT_REQUIREMENTS=["polars==1.32.3"]' \
--env 'IPYTHON_MCP_ENVIRONMENT_VARIABLES={"TASK_MODE":"offline"}' \
--env IPYTHON_MCP_LIBRARY_PATHS=/absolute/agent-libraries \
--env IPYTHON_MCP_PRELOAD_MODULES=polars,my_agent_lib \
--env 'IPYTHON_MCP_MODULE_ALIASES={"polars":"pl","my_agent_lib":"lib"}' \
-- ipython-mcpEquivalent project-scoped Codex configuration:
[mcp_servers.ipython]
command = "ipython-mcp"
startup_timeout_sec = 310
[mcp_servers.ipython.env]
IPYTHON_MCP_ENVIRONMENT_WORKSPACE = "/absolute/task-environments"
IPYTHON_MCP_ACTIVE_ENVIRONMENT = "analytics-v1"
IPYTHON_MCP_ENVIRONMENT_REQUIREMENTS = '["polars==1.32.3"]'
IPYTHON_MCP_ENVIRONMENT_VARIABLES = '{"TASK_MODE":"offline"}'
IPYTHON_MCP_LIBRARY_PATHS = "/absolute/agent-libraries"
IPYTHON_MCP_PRELOAD_MODULES = "polars,my_agent_lib"
IPYTHON_MCP_MODULE_ALIASES = '{"polars":"pl","my_agent_lib":"lib"}'Startup order is fixed:
Validate the workspace, safe environment name, bounded PEP 508 requirements, variables, paths, module names, and aliases.
Create a temporary uv environment and atomically rename it into place, or verify an existing environment's metadata.
Prepend the selected site-packages, then apply configured variables and trusted library paths.
Import every preload and validate its unique, non-protected alias.
Construct the only InteractiveShell and bind the preloaded modules.
The selected environment and all startup configuration are immutable for that server process. Change configuration by restarting the server. A different dependency set should use a new environment name; no environment create, switch, list, delete, or activate MCP tools exist.
Configuration, path, uv, dependency, preload, or binding failures abort the
lifespan before a shell is exposed. Temporary directories are removed, process
environment and sys.path changes are rolled back, and the project is not
modified. Diagnostics identify the failed phase, are bounded by
IPYTHON_MCP_MAX_TEXT_CHARS, redact configured variable values and URL
credentials, and are never persisted in the environment metadata.
Environment variable | Meaning |
| Absolute workspace outside the project; configure with |
| Safe environment name ( |
| JSON array of bounded PEP 508 requirements; requires an active environment. |
| JSON object of environment-variable string values applied before preloads. |
| Positive finite timeout for each uv phase; default |
| Trusted library directories separated by the platform path separator. |
| Comma-separated modules imported before shell construction. |
| JSON object mapping configured preload modules to unique safe bindings. |
| Returned text and startup-diagnostic bound; default |
| Representation bound; default |
| Traceback bound; default |
| Retained collection/discovery items; default |
| Retained display payloads per execution; default |
| Nested JSON translation depth; default |
| Dynamic MCP tool-name bound; default |
| Dynamic description bound; default |
| Dynamic registration bound; default |
stdout and stderr use streaming prefix sinks whose retained memory is independent of produced output size. Exact omitted-character counts accompany their truncation flags. Display items are capped as they arrive. Results, representations, docs, signatures, filenames, error messages, and tracebacks use deterministic depth, item, and character bounds.
Names beginning with _, IPython bindings (In, Out, get_ipython,
exit, quit, and open), and configured preload aliases are protected from
remove, reset, and dynamic registration. reset restores configured
modules. Default logs contain tool name and outcome only—not code, arguments,
results, namespace values, environment-variable values, or traceback locals.
A backing name must be a non-protected top-level Python identifier. Dynamic
tool names start with an ASCII letter and contain only letters, digits, _, or
-. Stable-name, dynamic-name, and backing-symbol collisions are rejected.
Supported parameters use resolvable annotations composed from str, int,
float, bool, None, bounded containers, unions/optionals, and JSON-safe
Literal values. Positional-only parameters, variadics, unresolved or
unsupported annotations, non-JSON defaults, coroutine functions, generators,
and async/generator callable objects are rejected.
The schema fingerprint is SHA-256 over sorted compact input-schema JSON.
Body-only replacement with an identical schema stays callable through the
current live binding. A signature-affecting change makes the registration
stale until explicit re-registration. Delete/remove invalidate the affected
registration; reset clears the catalog. Catalog changes emit
notifications/tools/list_changed when the client supports it.
F-005 is a deliberate breaking simplification. It removes the F-004
multiprocessing worker, controller, versioned IPC, pipes, reader/writer loops,
health probes, worker replacement, runtime epochs, stale-response handling,
process admission queue, queue limits, worker startup/interruption grace,
hard operation timeout recovery, worker shutdown logic, response runtime
metadata, and runtime_status tool.
Remove these obsolete settings from client configuration:
IPYTHON_MCP_OPERATION_TIMEOUT_SECONDS
IPYTHON_MCP_INTERRUPTION_GRACE_SECONDS
IPYTHON_MCP_WORKER_STARTUP_TIMEOUT_SECONDS
IPYTHON_MCP_MAX_PENDING_OPERATIONS
IPYTHON_MCP_QUEUE_WAIT_TIMEOUT_SECONDS
IPYTHON_MCP_MAX_IPC_MESSAGE_BYTES
If callers relied on forced termination, queue overload responses, recovery epochs, or status polling, they must instead apply a client-side observation timeout and restart the entire trusted local server when code does not return. A client-side timeout does not imply that Python stopped.
Put a reusable module in a configured trusted library directory.
Preload it or import it with execute.
Discover functions with list or search and call them with
call_function.
Edit the module using normal file tools.
Call reload with the explicit module name.
Repository-native checks are:
uv sync --extra dev
uv run pytest
uv run python scripts/release_matrix.py
uv buildThe tests cover the unconfigured startup path, direct same-process ownership, persistent state and dynamic tools, absence of runtime child processes and IPC modules, output bounds, startup variables/paths/preloads, uv reuse, conflicting pure-Python dependency versions across separate restarts, clean/redacted failures, stdio packaging flow, and the explicitly non-preemptive contract.
Call a live callable by name with a JSON object of keyword arguments.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| arguments | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| name | Yes | |
| error | No | |
| result | No | |
| runtime | No | |
| truncated | No | |
| name_truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action 'call' but does not mention potential side effects, error conditions, security considerations, or whether the call is synchronous. This is a significant gap for a tool that invokes arbitrary callables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant information. Every word contributes to understanding the tool's purpose and its key parameters. It is concise and appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no annotations, no parameter descriptions in the schema, and only a minimal description. It does not explain how to discover available callables (e.g., via 'list'), what happens if the callable does not exist, or any safety implications of executing arbitrary functions. The existing output schema may cover return values, but other essential context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains both parameters: 'by name' clarifies that 'name' is the identifier of the callable, and 'with a JSON object of keyword arguments' provides meaning for 'arguments'. However, the schema allows 'arguments' to also be a string, which is not addressed, leaving ambiguity about that format. Despite the 0% schema description coverage, the description does add meaningful context beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (call), the resource (a live callable), and the method (by name with a JSON object of keyword arguments). It is specific and unambiguous about what the tool does. However, it does not explicitly distinguish itself from sibling tool 'execute', which could be similarly interpreted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a general sense of when to use the tool (when you want to call a callable), but it offers no guidance on when not to use it or contrasts with alternatives like 'execute', 'search', or 'inspect'. There is no mention of prerequisites such as the callable needing to be registered first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute Python source in the persistent IPython namespace.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| result | No | |
| status | Yes | |
| stderr | No | |
| stdout | No | |
| runtime | No | |
| truncated | No | |
| display_data | No | |
| execution_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key behavioral trait (persistent IPython namespace), but does not mention potential side effects, safety concerns (e.g., arbitrary code execution risks), or error handling behavior. The added namespace context provides some value beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repeated information. Every word adds value, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description is moderately complete. It covers the core behavior but omits usage context and potential risks, which are important for an execution tool. Without annotations, the burden is higher, so it falls short of being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'code' with no description (0% coverage), so the description must compensate. It does by clarifying that the input is 'Python source', adding meaning beyond the generic string type. However, it lacks format details or examples, so it only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Execute Python source') and its scope ('in the persistent IPython namespace'). It distinguishes itself from siblings like 'call_function' by focusing on arbitrary Python code execution rather than specific function calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or situations where other tools would be preferred. The persistent namespace hints at a use case, but this is not made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect one live name with bounded metadata and explicit truncation flags.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| kind | No | |
| name | Yes | |
| error | No | |
| module | No | |
| runtime | No | |
| callable | No | |
| signature | No | |
| truncated | No | |
| documentation | No | |
| qualified_type | No | |
| representation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds behavioral hints like 'bounded metadata' and 'explicit truncation flags,' but does not disclose whether the operation is read-only, if it requires permissions, or any side effects. 'Inspect' implies read-only, but it's not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no redundant words. It efficiently communicates the core purpose and key behavioral traits.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and has an output schema, but the description lacks usage guidance, error conditions, or what 'bounded metadata' specifically entails. It is minimally adequate but leaves gaps for an agent to infer behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the 'name' parameter as a 'live name,' adding that it refers to an existing entity. However, it doesn't elaborate on format, constraints, or behavior beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Inspect' with a clear resource ('one live name'), giving a specific purpose. It distinguishes from siblings like 'list' and 'search' by indicating a single-name inspection, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The sibling list provides context, but the description itself does not state preferred use cases, exclusions, or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List callable functions currently available in the live namespace.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| error | No | |
| runtime | No | |
| functions | Yes | |
| truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It states the core operation and adds useful context (live namespace, currently available). The read-only nature is implicit in 'List' and no side effects are suggested, which is adequate for this simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of nine words, front-loaded with the verb. It is concise and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete. It clearly states what the tool does and the scope, and the output schema covers return values. No additional detail is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter semantics. The baseline for 0 params is 4, and the description provides no unnecessary parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('List') and the resource ('callable functions'), and adds the scoping phrase 'currently available in the live namespace.' This distinguishes it from sibling tools like search or inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is used to enumerate callable functions in the live namespace. However, it does not explicitly state when not to use it or name alternatives, though the context is sufficient for a simple listing operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explicitly publish one supported top-level synchronous live callable.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| tool_name | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| runtime | No | |
| registration | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of disclosing side effects. It says 'explicitly publish' but does not state whether this makes the callable immediately invokeable, whether it overwrites existing registrations, or what happens if the callable is not 'supported'. There is no mention of permissions, failure modes, or the nature of the 'live' behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but the wording is cryptic and lacks structure. It does not front-load the most useful information, and the meaning is obscured by excessive modifiers, making it less effective than a clear, concise sentence would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 3 parameters, no annotations, and an output schema, the description provides almost no context. It fails to explain what the tool returns, what constitutes a 'supported' callable, or any behavioral expectations. This is inadequate for a tool that performs a registration action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description should compensate by explaining the parameters. It does not mention 'name', 'tool_name', or 'description' at all. The phrase 'one supported ... callable' vaguely hints that 'name' might be the callable's identifier, but it leaves all parameter semantics undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'publish' and mentions a 'callable' as the resource, which clearly indicates registration. However, the phrase 'supported top-level synchronous live callable' is filled with jargon and does not clarify what 'supported' means or what 'top-level' refers to, making the purpose less clear than it could be.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'list', 'execute', 'remove', or 'unregister_tool'. The description does not mention any prerequisites, nor does it explain situations where this tool should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reload explicitly named imported modules and refresh their bindings.
| Name | Required | Description | Default |
|---|---|---|---|
| modules | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| results | Yes | |
| runtime | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It mentions refreshing bindings but does not disclose potential side effects, whether the operation is safe, required permissions, or impact on dependent modules.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the action and object clearly, earning full credit for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with an output schema, the description omits crucial contextual details for a dynamic reload operation, such as when it should be used, what side effects occur, and how it interacts with the runtime environment. The sparse description is inadequate for a tool that likely modifies execution state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'modules' parameter by describing it as 'explicitly named imported modules', which clarifies the input format as a list of module names. However, with 0% schema coverage, it leaves gaps such as how module names should be formatted and error behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (reload) on a specific resource (imported modules) and adds the qualifier 'explicitly named' to indicate scope. This distinguishes it from generic operations like execute or list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as reset or execute. There is no mention of prerequisites, exclusions, or typical use cases beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove unprotected top-level names and report every requested partition.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| refused | No | |
| removed | No | |
| runtime | No | |
| unknown | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It reveals that removal is limited to 'unprotected' names and mentions reporting partitions, but it does not explain what happens to protected names, what a partition is, whether the operation is reversible, or any error conditions. This is a significant transparency gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and therefore concise in length, but it sacrifices clarity for brevity. The two clauses ('Remove unprotected top-level names' and 'report every requested partition') feel disconnected, and the unusual terminology requires elaboration. It is not appropriately sized because important details are omitted, making it under-specified rather than genuinely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no annotations, and a vague description, it is not complete enough for an agent to use correctly. The presence of an output schema does not cover the need to explain protected vs. unprotected names, partition semantics, or how the tool handles out-of-scope requests. The description leaves too many critical questions unanswered for a tool that performs destructive operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines 'names' as an array of strings with no descriptions, and schema description coverage is 0%. The description must compensate but only implies that 'names' refers to the top-level names to remove. It does not clarify what constitutes an 'unprotected' name, what value formats are acceptable, or how 'partitions' relate to the parameter. The description adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' and identifies a resource ('unprotected top-level names'), giving a general sense of purpose. However, the meaning of 'unprotected top-level names' is ambiguous, and the phrase 'report every requested partition' is confusing. It does not clearly distinguish from sibling tools like 'unregister_tool' or 'reset', which also involve removal or state changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. It implies usage when removal of 'unprotected top-level names' is desired, but that is insufficient for an agent to choose confidently between this and related tools such as 'unregister_tool'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove user-created names while preserving runtime and configured bindings.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| removed | No | |
| runtime | No | |
| execution_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It explains that user-created names are removed while runtime and configured bindings are preserved, which is transparent about scope. However, it doesn't clarify what 'names' refers to, whether removal is irreversible, or any side effects, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and outcome. It is concise with no wasted words, effectively conveying the core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters) and the presence of an output schema, the description is largely complete. It covers the key behavior and exclusions, though the ambiguity around 'names' and the lack of explicit usage guidance means it's not perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and it adds context about the tool's purpose, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: removing user-created names while preserving runtime and configured bindings. It uses a specific verb ('remove') and resource ('user-created names'), and the preservation note helps distinguish it from sibling tools like 'remove'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives like 'remove'. The description implies usage for resetting names, but it does not state conditions, exclusions, or mention other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report bounded out-of-band worker, queue, epoch, and recovery metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| epoch | Yes | |
| error | No | |
| state | Yes | |
| queue_depth | Yes | |
| operation_active | Yes | |
| latest_namespace_state | No | |
| latest_interruption_kind | No | |
| replacement_startup_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only reporting action but does not clarify side effects, required permissions, output behavior, or the meaning of 'bounded out-of-band' metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no wasted words. It is front-loaded with the action verb and immediately specifies the subject matter, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of parameters and presence of an output schema, the description provides adequate context for a status-reporting tool. The key gap is the ambiguous 'bounded out-of-band' phrasing, but overall the description is reasonably complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter semantics. The input schema already covers everything (empty object, additionalProperties false), earning the baseline score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Report' with specific resources ('worker, queue, epoch, and recovery metadata'), making the tool's function clear. It is distinguishable from siblings like 'list' or 'execute', though the phrase 'bounded out-of-band' is somewhat jargon-heavy and not fully explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or relationships to sibling tools, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search visible live namespace objects by exact or partial name.
| Name | Required | Description | Default |
|---|---|---|---|
| exact | No | ||
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| error | No | |
| results | Yes | |
| runtime | No | |
| truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It adds context that objects are 'visible live' and search can be exact or partial, but does not explain case sensitivity, ordering, or the meaning of 'live namespace objects'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, front-loaded with the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered. The description covers core search intent but leaves ambiguity around 'namespace objects' and lacks usage guidance relative to sibling tools. Adequate for a simple search tool but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning to query (name) and exact (exact/partial), but does not mention the limit parameter or default behavior beyond the schema. Partial coverage only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'search' with a clear resource 'visible live namespace objects' and matching modes 'exact or partial name'. This clearly distinguishes it from siblings like list (browse all) and execute/call_function (run objects).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding objects by name but does not explicitly state when to use search vs list or other alternatives. No exclusions or context about prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove requested dynamic tool registrations without affecting stable tools.
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes |
| Name | Required | Description |
|---|---|---|
| ok | Yes | |
| error | No | |
| runtime | No | |
| unknown | No | |
| revision | Yes | |
| unregistered | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral guarantee: it does not affect stable tools. However, with no annotations, it doesn't mention error handling, idempotency, or the effects of unregistering an in-use tool, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of eight words, front-loading the action and scope without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers its core purpose and key qualification. With an output schema present, return values are documented elsewhere. It doesn't address edge cases like non-existent names, but the tool is simple enough that the description is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lists only 'names' (array of strings) with no description, and the tool description only hints at 'requested dynamic tool registrations' without explicitly detailing what values are expected or any constraints. Schema coverage is 0%, and the description adds minimal semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Remove' with a targeted object 'dynamic tool registrations' and adds a qualifier 'without affecting stable tools' that distinguishes it from sibling tools like 'remove' or 'reset'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool applies only to dynamic tool registrations, implying that stable tools are managed elsewhere. It provides clear context but does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0call_functionexecuteinspectlistregister_toolreloadremoveresetruntime_statussearchunregister_toolTools are mostly distinct, but `list`, `search`, and `inspect` all deal with namespace introspection and could be confused at a glance. `remove` vs `reset` also have overlapping deletion semantics, though descriptions clarify boundaries.
Naming uses a consistent snake_case imperative style (e.g., `execute`, `inspect`, `register_tool`). A few names like `runtime_status` are noun-like rather than verb_noun, but overall the pattern is predictable and readable.
11 tools is well within the ideal 3-15 range and each tool serves a clear purpose for managing a live IPython namespace. The count feels appropriate for the server's stated scope.
The toolset covers core operations: executing code, inspecting objects, managing namespace bindings, and runtime status. Minor gaps like fetching full history or handling asynchronous execution exist, but agents can work around them.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP runtime where the agent is the operator: sign up by tool call, publish your own tools.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/husams/ipython-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
