Smarter Project MCP Server

Every Smarter platform runs an MCP server that answers questions about The Smarter Project from its own source code and documentation. It is a Model Context Protocol server, over Streamable HTTP, that reads every public repository of the smarter-sh GitHub organization: the platform and its documentation, the command-line interface, the Python, Node.js and Go SDKs, the VS Code extension, the SmarterChat component, the quick start, and the cloud infrastructure.

Its main clients are the platform’s own built-in MCPClients, smarter_project and smarter_project_github*, which give LLMClients such as smarter, smarter_developer and smarter_sdk_guide their answers about Smarter. Any other MCP client can use it too, e.g. Claude Code, an IDE, or another platform’s MCPClient.

It is an internal platform service, not a resource: there is no manifest to apply, and nothing to configure.

Endpoints

The server is mounted under /api/v1/mcp/ of the platform’s own domain:

Endpoint

Reads

/api/v1/mcp/smarter-project/

Every repository. Each tool takes a repository argument, and the search tools search every repository when it is omitted.

/api/v1/mcp/smarter-project/<repository>/

One repository, e.g. /api/v1/mcp/smarter-project/smarter-cli/. The tools have no repository argument.

The repositories are smarter, smarter-cli, smarter-python, smarter-nodejs, smarter-golang, smarter-vscode-yaml, smarter-infrastructure, smarter-chat and smarter-deploy, as declared in smarter.apps.mcpserver.repositories.

The server requires no authentication. It is read-only, and serves public repositories. It is stateless: it answers every POST with application/json, issues no Mcp-Session-Id, and answers GET and DELETE with 405 Method Not Allowed, so any of the platform’s pods can answer any request. It speaks the initialize handshake of protocol versions 2024-11-05 through 2025-11-25.

Because it requires no authentication, each client IP address may send at most SMARTER_MCPSERVER_RATE_LIMIT requests a minute, 1200 by default, and is answered 429 Too Many Requests, with a Retry-After header, beyond that. The platform’s own MCPClients count too: they connect from the platform’s egress addresses, and each tool call is about three requests, so a busy platform may need a higher limit. 0 disables it. See smarter.apps.mcpserver.ratelimit.

To try it, list its tools with curl:

curl -s https://platform.example.com/api/v1/mcp/smarter-project/smarter-cli/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

or add it to Claude Code:

claude mcp add --transport http smarter-project https://platform.example.com/api/v1/mcp/smarter-project/

Tools

Every tool is read-only, and returns Markdown, with links to the file on GitHub, at the indexed commit, and, for a page of the Sphinx documentation, to the page on docs.smarter.sh.

Tool

What it does

get_repository_overview

What a repository contains, its GitHub url, its indexed commit, its top-level folders and files, and its README. Without a repository, a table of every repository.

search_documentation

Ranked passages of the documentation: the Sphinx sources in docs/source, READMEs, and other reStructuredText and Markdown files.

search_code

Ranked files of source code and configuration, with their matching lines, optionally under a path.

read_file

A file, with line numbers, 400 lines at a time, from start_line to end_line.

list_files

The folders, with their number of files, and the files in a folder.

A search ranks files in the database, without embeddings. A quoted phrase is one search term, and so is an identifier such as smarter_settings.environment_platform_domain. Each term counts for more the rarer it is, and a term in a file’s path or title counts for more than one in its text. See smarter.apps.mcpserver.search.

The server’s instructions, which MCPClients with includeInstructions: true add to the LLM’s system prompt, tell the LLM to answer from the tools rather than from memory, and to cite its sources.

The Index

The server reads its own index of the repositories, in the platform’s database, rather than GitHub, so that a tool call costs one or two queries. smarter.apps.mcpserver.indexer.index_repository() keeps each repository’s index up to date with its main branch:

  1. It asks the GitHub api for the branch’s latest commit. A repository that has not changed costs this one small request, so the hourly refresh of every repository stays well within GitHub’s limit of 60 unauthenticated requests an hour.

  2. Otherwise, it downloads the repository’s archive at that commit, and reads its text files in memory, without extracting anything to disk. It keeps documentation and source code, and skips binaries, vendored and generated files, lock files, and files larger than 256 KB.

  3. It replaces the repository’s files in one transaction, so that a search never sees a partial index. If indexing fails, the existing index is kept, and the failure is recorded in the index’s error.

Celery Beat runs index_repositories() hourly, on the platform’s operational queue, and manage.py initialize_platform queues it, so a new platform is indexed within minutes of being initialized. A tool that is called on a repository that is not indexed yet says so, and queues the repository. To index the repositories now:

python manage.py index_smarter_project
python manage.py index_smarter_project --repository smarter-cli --force
python manage.py index_smarter_project --queue

The indexes are the RepositoryIndex and RepositoryFile rows of the Django admin’s MCPServer app, which shows each repository’s commit, file count and last error.

The Built-in MCPClients

The smarter_project and smarter_project_github* MCPClients that manage.py add_builtin_mcpclients applies read the MCP server of the platform that applies them. Their manifests, in smarter/apps/mcpclient/data/mcpclients, are templates, *.yaml.tpl, whose endpointUrl is filled in when they are applied:

endpointUrl: ${environment_platform_scheme}://${environment_platform_domain}/api/v1/mcp/smarter-project/smarter-cli/

environment_platform_domain is smarter_settings.environment_platform_domain, e.g. alpha.platform.example.com, and environment_platform_scheme is the scheme of smarter_settings.environment_url, https. In local development, they are http and localhost:9357. An MCPClient may connect to a loopback host only in the local environment: see smarter.apps.mcpclient.connection.validate_endpoint_url().

---
# Every GitHub repository of The Smarter Project, through the Smarter Project MCP server of this
# platform, which indexes the repositories from GitHub every hour: the platform and its
# documentation, https://docs.smarter.sh, the command-line interface, the Python, Node.js and Go
# SDKs, the VS Code extension, the SmarterChat component, the quick start, and the cloud
# infrastructure.
# Documentation: https://docs.smarter.sh/en/latest/smarter-platform/smarter-project-mcp-server.html
#
# Its tools take a repository argument, and the search tools search every repository when it is
# omitted. To read one repository only, use one of the smarter-project-github*.yaml.tpl manifests.
#
# This file is a string.Template: add_builtin_mcpclients fills in the scheme and domain of the
# platform that applies it, from smarter_settings.environment_url and
# smarter_settings.environment_platform_domain, e.g. https://alpha.platform.example.com, or
# http://localhost:9357 in local development, so that this MCPClient reads the MCP server of
# its own platform.
#
# The MCP server requires no authentication. Its tools are read-only.
apiVersion: smarter.sh/v1
kind: MCPClient
metadata:
  name: smarter_project
  description: Searches and reads the documentation, https://docs.smarter.sh, and the source code of every GitHub repository of The Smarter Project.
  version: 1.0.0
  tags:
    - smarter
    - documentation
    - github
    - code
  annotations:
    - smarter.sh/mcpclient/documentation: https://docs.smarter.sh/en/latest/smarter-platform/smarter-project-mcp-server.html
    - smarter.sh/mcpclient/repository: https://github.com/smarter-sh
spec:
  config:
    transport: http
    endpointUrl: ${environment_platform_scheme}://${environment_platform_domain}/api/v1/mcp/smarter-project/
    authType: none
    allowedTools:
      - get_repository_overview
      - search_documentation
      - search_code
      - read_file
      - list_files
    includeInstructions: true
    timeout: 30
    cacheTtl: 3600
    isActive: true
    priority: 100

The example LLMClients smarter_developer, which helps developers understand and contribute to the platform, and smarter_sdk_guide, which helps programmers call it from Python, Node.js, Go and the command line, are built on them, in smarter/apps/llmclient/data/llm-clients.

Note

Experimental. The Smarter Project MCP server was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental.

Technical Reference