Usage

This section covers the installation, configuration and usage of the sphinx-mcp extension for Sphinx.

Installation

You can install sphinx-mcp using pip as pip install sphinx-mcp. Alternatively, you can add it to your existing project a project management tool, such as uv, by calling uv add sphinx-mcp. Once installed, you can use it in your Sphinx project by adding it to the extensions list in your Sphinx conf.py file and add the MCP servers configuration, as shown below.

Configuration

To document only one MCP server, you can set the allow_only_one_mcp_server configuration option to True (it defaults to False if not specified).

extensions = [
    "sphinx_mcp",
]

mcp_config = {
   "mcpServers": {
      "pymcp": {
         "transport": "stdio",
         "command": "python",
         "args": ["-m", "pymcp.server"],
      }
   }
}

allow_only_one_mcp_server = True

To document multiple MCP servers, you can specify them in the mcpServers dictionary. Remember to set the allow_only_one_mcp_server to False or not set it at all, as it defaults to False. In the following example, two MCP servers are configured: one using the pymcp library and another using the @modelcontextprotocol/server-everything package, which is not even implemented in Python!

extensions = [
    "sphinx_mcp",
]

mcp_config = {
   "mcpServers": {
      "pymcp": {
         # Local stdio server
         "transport": "stdio",
         "command": "python",
         "args": ["-m", "pymcp.server"],
      },
      "everything": {
         # Make sure to run `nvm use --lts` before running this.
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-everything"],
      }
   }
}

In both the single and multiple server configurations, only stdio transport is illustrated. However, servers with sse and streamable-http transports can also be configured. For stdio transport, the command necessary to run the server must execute successfully as Sphinx will use it to connect to the server. This necessitates having the necessary runtime environment set up, such as having the correct Python version or Node.js version installed.

Directives

The extension provides the following directives to document MCP servers. Each directive belongs to the domain mcpdocs.

mcpdocs::tools

This directive is used to document the tools available in one or more MCP servers. An optional argument can be provided to specify the MCP server to document. If no argument is provided, it defaults to all the servers configured in the mcp_config dictionary. If the argument is absent, each tool listed will be prefixed with the server name, followed by two colons, e.g., pymcp::greet.

Arguments:

server name (optional)

mcpdocs::prompts

This directive is used to document the prompts available in one or more MCP servers. Similar to the tools directive, an optional argument can be provided to specify the MCP server to document. If no argument is provided, it defaults to all the servers configured in the mcp_config dictionary. If the argument is absent, each prompt listed will be prefixed with the server name, followed by two colons, e.g., pymcp::code_prompt.

Arguments:

server name (optional)

mcpdocs::resources

This directive is used to document the resources available in one or more MCP servers. An optional argument can be provided to specify the MCP server to document. If no argument is provided, it defaults to all the servers configured in the mcp_config dictionary. If the argument is absent, each resource listed will be prefixed with the server name, followed by two colons, e.g., pymcp::resource_logo.

Arguments:

server name (optional)

mcpdocs::resource_templates

This directive is used to document the resource templates available in one or more MCP servers. An optional argument can be provided to specify the MCP server to document. If no argument is provided, it defaults to all the servers configured in the mcp_config dictionary. If the argument is absent, each resource template listed will be prefixed with the server name, followed by two colons, e.g., pymcp::resource_unicode_modulo10.

Arguments:

server name (optional)

Limitations

The extension currently only has the aforementioned directives. It does not contain any roles yet. In addition, the generation of indices for the documented tools, prompts, resources, and resource templates is not implemented yet.