Skip to main content

atmos.mcp

The atmos.mcp function runs atmos mcp through the current Atmos executable. Use it to inspect, test, and configure the Model Context Protocol servers in atmos.yaml and the AI clients that use them.

Usage​

atmos.mcp(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and its positional arguments as strings before the keyword arguments. The call atmos.mcp("tools", "aws-docs") runs atmos mcp tools aws-docs.

SubcommandPurpose
listList configured MCP servers.
statusShow the status of all MCP servers.
toolsList the tools from an MCP server.
testTest connectivity to an MCP server.
restartValidate that an MCP server can stop and restart cleanly.
addAdd an MCP server to mcp.servers in atmos.yaml.
removeRemove an MCP server from mcp.servers in atmos.yaml.
exportExport .mcp.json from the MCP server configuration.
installInstall configured MCP servers into AI client config files.
uninstallRemove installed MCP servers from AI client config files.
startStart the Atmos MCP server.

See the atmos mcp command reference for each subcommand's flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after mcp, in order: the subcommand and its positional arguments, such as a server name. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "format" becomes --format. For start, the keys "transport", "host", and "port" become --transport, --host , and --port. For tools, the keys "format", "columns", and "sort" shape the output.

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

List the configured servers​

servers = atmos.mcp("list", output = "capture")
print(servers.stdout)

Read the tools of a server as JSON​

tools = atmos.mcp("tools", "aws-docs", flags = {"format": "json"}, output = "capture")
for tool in json.decode(tools.stdout):
    print(tool)

Fail when a server is unreachable​

probe = atmos.mcp("test", "aws-docs", output = "capture", check = False)
if probe.exit_code != 0:
    fail("The aws-docs MCP server did not respond:\n" + probe.stderr)
note

Inspection subcommands such as list, status, tools, and test finish on their own and suit scripts. The start subcommand runs the server until it is stopped, so the script waits at that call until the server exits. Atmos prints its experimental notice when the script runs MCP commands.

Related​