Semantic Code Search MCP server
Commit Nov 15, 2026Enables AI coding agents to perform semantic searches, symbol analysis, and file reading across an indexed codebase using Elasticsearch.
Also known as elastic/semantic-code-search-mcp-server
- Stars
- 13
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- —
What is Semantic Code Search MCP?
Semantic Code Search enables AI coding agents to perform semantic searches, symbol analysis, and file reading across an indexed codebase using Elasticsearch. It exposes 6 tools, such as semantic_code_search, map_symbols_by_query, symbol_analysis.
Summary generated from the project's README
About Semantic Code Search MCP server
AI coding agents can explore and understand complex codebases through semantic search and symbol analysis using this MCP server. It connects to an Elasticsearch instance containing a locations-first index model, which requires the ELSER model to be deployed. The server provides structured access to code chunks, file paths, and git metadata, allowing agents to navigate repositories with high precision.
Developers can deploy the server using Docker in either STDIO mode for local agent communication or HTTP mode for network-accessible environments. When running in HTTP mode, the server supports OAuth 2.0 bearer token authentication via OIDC-compliant providers like Okta or Keycloak. This ensures secure access for clients such as Claude Code, VS Code, or Cursor.
Specific tools include semantic_code_search for querying code chunks with KQL filters, symbol_analysis to report on definitions and call sites, and read_file_from_chunks to reconstruct file content. It also offers map_symbols_by_query to locate symbols across directories and document_symbols to identify areas needing better documentation.
What you can do with it
- 1Perform semantic codebase searchesAsk an AI agent to find specific logic or functionality within a large repository using natural language queries.
- 2Analyze symbol relationshipsRequest a detailed report on a specific function to see where it is defined and how it is called throughout the project.
- 3Map symbols across filesHave an agent identify all files within a specific directory that contain a particular symbol.
- 4Investigate codebase tasksUse a structured workflow to explore a codebase and formulate a plan for implementing a new feature.
Written from the project's README. Every use case is checked against a quote from it.
Semantic Code Search MCP tools 6
Detected from the READMEsemantic_code_searchmap_symbols_by_querysymbol_analysisread_file_from_chunksdocument_symbolsauth_status
Configuration
ELASTICSEARCH_ENDPOINTSCS_MCP_OAUTH_ALLOWED_CLIENT_IDSSCS_MCP_OAUTH_AUDIENCESCS_MCP_OAUTH_CLIENT_IDSCS_MCP_OAUTH_CLIENT_SECRETSCS_MCP_OAUTH_ENABLEDSCS_MCP_OAUTH_ISSUERSCS_MCP_OAUTH_REQUIRED_SCOPESSCS_MCP_SERVER_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableelastic/semantic-code-search-mcp-server is public and reachablegithub.com/elastic/semantic-code-search-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-10github.com/elastic/semantic-code-search-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSemantic Code Search MCP Server
This project includes a Model Context Protocol (MCP) server that exposes the indexed data through a standardized set of tools. This allows AI coding agents to interact with the indexed codebase in a structured way.
Prerequisites
You must index your code base with the Semantic Code Search Indexer found here: https://github.com/elastic/semantic-code-search-indexer
Index model expected by this MCP server
This MCP server expects the locations-first index model from indexer PR elastic/semantic-code-search-indexer#135:
<index>stores content-deduplicated chunk documents (semantic search + metadata).<index>_locationsstores one document per chunk occurrence (file path + line ranges + directory/git metadata) and references chunks bychunk_id.
Several tools query <index>_locations and join back to <index> via chunk_id (typically using mget).
Running with Docker
The easiest way to run the MCP server is with Docker. The server is available on Docker Hub as simianhacker/semantic-code-search-mcp-server.
To ensure you have the latest version of the image, run the following command before running the server:
docker pull simianhacker/semantic-code-search-mcp-server
HTTP Mode
This mode is useful for running the server in a containerized environment where it needs to be accessible over the network.
docker run --rm -p 3000:3000 \
-e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
simianhacker/semantic-code-search-mcp-server
Replace <your_elasticsearch_endpoint> with the actual endpoint of your Elasticsearch instance.
STDIO Mode
This mode is useful for running the server as a local process that an agent can communicate with over stdin and stdout.
With Elasticsearch Endpoint:
docker run -i --rm \
-e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
simianhacker/semantic-code-search-mcp-server \
node dist/src/mcp_server/bin.js stdio
With Elastic Cloud ID:
docker run -i --rm \
-e ELASTICSEARCH_CLOUD_ID=<your_cloud_id> \
-e ELASTICSEARCH_API_KEY=<your_api_key> \
simianhacker/semantic-code-search-mcp-server \
node dist/src/mcp_server/bin.js stdio
The -i flag is important as it tells Docker to run the container in interactive mode, which is necessary for the server to receive input from stdin.
Connecting a Coding Agent
You can connect a coding agent to the server in either HTTP or STDIO mode.
HTTP Mode:
For agents that connect over HTTP, like the Gemini CLI, you can add the following to your ~/.gemini/settings.json file:
{
"mcpServers": {
"Semantic Code Search": {
"trust": true,
"httpUrl": "http://localhost:3000/mcp/",
}
}
}
STDIO Mode:
For agents that connect over STDIO, you need to configure them to run the Docker command directly. Here's an example for the Gemini CLI in your ~/.gemini/settings.json file:
{
"mcpServers": {
"SemanticCodeSearch": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "ELASTICSEARCH_CLOUD_ID=<your_cloud_id>",
"-e", "ELASTICSEARCH_API_KEY=<your_api_key>",
"-e", "ELASTICSEARCH_INDEX=<your_index>",
"simianhacker/semantic-code-search-mcp-server",
"node", "dist/src/mcp_server/bin.js", "stdio"
]
}
}
}
Remember to replace the placeholder values for your Cloud ID, API key, and index name.
Setup and Installation
1. Prerequisites
- Node.js (v20 or later)
- npm
- An running Elasticsearch instance (v8.0 or later) with the ELSER model downloaded and deployed.
2. Clone the Repository and Install Dependencies
git clone <repository-url>
cd semantic-code-search-mcp-server
npm install
3. Configure Environment Variables
Copy the .env.example file and update it with your Elasticsearch credentials.
cp .env.example .env
4. Compile the Code
The multi-threaded worker requires the project to be compiled to JavaScript.
npm run build
Running the Server
The MCP server can be run in two modes:
1. Stdio Mode:
This is the default mode. The server communicates over stdin and stdout.
npm run mcp-server
2. HTTP Mode: This mode is useful for running the server in a containerized environment like Docker.
npm run mcp-server:http
The server will listen on port 3000 by default. You can change the port by setting the PORT environment variable.
Usage with NPX
You can also run the MCP server directly from the git repository using npx. This is a convenient way to run the server without having to clone the repository.
Stdio Mode:
ELASTICSEARCH_ENDPOINT=http://localhost:9200 npx github:elastic/semantic-code-search-mcp-server
HTTP Mode:
PORT=8080 ELASTICSEARCH_ENDPOINT=http://localhost:9200 npx github:elastic/semantic-code-search-mcp-server http
Available Prompts
| Prompt | Description |
|---|---|
StartInvestigation |
This prompt helps you start a "chain of investigation" to understand a codebase and accomplish a task. It follows a structured workflow that leverages the available tools to explore the code, analyze its components, and formulate a plan. |
Example:
/StartInvestigation --task="add a new route to the kibana server"
Available Tools
The MCP server provides the following tools:
| Tool | Description |
|---|---|
semantic_code_search |
Performs a semantic search on the code chunks in the index. This tool can combine a semantic query with a KQL filter to provide flexible and powerful search capabilities. |
map_symbols_by_query |
Query for a structured map of files containing specific symbols, grouped by file path. This is useful for finding all the symbols in a specific file or directory. Accepts an optional size parameter to control the number of files returned. |
symbol_analysis |
Analyzes a symbol and returns a report of its definitions, call sites, and references. This is useful for understanding the role of a symbol in the codebase. |
read_file_from_chunks |
Reads the content of a file from the index, providing a reconstructed view based on the most important indexed chunks. |
document_symbols |
Analyzes a file to identify the key symbols that would most benefit from documentation. This is useful for automating the process of improving the semantic quality of a codebase. |
auth_status |
Returns your current OAuth authentication status: client ID, granted scopes, and token expiry. Only available when SCS_MCP_OAUTH_ENABLED=true. Never includes the token value. |
Note: All of the tools accept an optional index parameter that allows you to override the ELASTICSEARCH_INDEX for a single query.
OAuth 2.0 Authentication (HTTP mode)
The HTTP server supports OAuth 2.0 bearer token authentication. When enabled, MCP clients (Claude Code, VS Code, Cursor) automatically discover the authorization server, obtain a token, and present it on every request. The server only validates tokens — it never issues them.
Prerequisites
- An OIDC-compliant authorization server (Okta, Auth0, Keycloak, etc.)
- The server must be reachable at its own dedicated (sub)domain. MCP clients fetch
/.well-known/oauth-protected-resourcefrom the root of the server's domain to discover the authorization server. This well-known URI must resolve at the domain root per RFC 8615 section 3 and RFC 9728 section 3. A subpath deployment (e.g.https://shared.example.com/my-mcp) will not work. - Okta app type must be SPA (not Web). MCP clients use the Authorization Code + PKCE flow (RFC 7636) without a client secret. Web app type requires a client secret for code exchange and will fail.
JWKS validation (default — no secrets required)
The server validates JWTs locally using the provider's public JWKS endpoint discovered from the issuer's OIDC configuration.
SCS_MCP_OAUTH_ENABLED=true
SCS_MCP_OAUTH_ISSUER=https://your-okta.okta.com/oauth2/default
SCS_MCP_SERVER_URL=https://your-server.example.com # must be the server's public URL
# Optional:
SCS_MCP_OAUTH_AUDIENCE=api://default # for Okta non-URL audience strings
SCS_MCP_OAUTH_REQUIRED_SCOPES=openid # space-separated; minimum "openid" for Okta
Token introspection (opt-in — requires client credentials)
Activated when both SCS_MCP_OAUTH_CLIENT_ID and SCS_MCP_OAUTH_CLIENT_SECRET are set. The server calls the provider's RFC 7662 introspection endpoint on every request. Use this when the provider issues opaque (non-JWT) tokens, or when real-time revocation checking is required.
SCS_MCP_OAUTH_ENABLED=true
SCS_MCP_OAUTH_ISSUER=https://your-keycloak.com/realms/myrealm
SCS_MCP_OAUTH_CLIENT_ID=my-resource-server
SCS_MCP_OAUTH_CLIENT_SECRET=super-secret
SCS_MCP_SERVER_URL=https://your-server.example.com
Docker (HTTP mode with OAuth)
docker run --rm -p 3000:3000 \
-e ELASTICSEARCH_ENDPOINT=https://... \
-e SCS_MCP_OAUTH_ENABLED=true \
-e SCS_MCP_OAUTH_ISSUER=https://your-okta.okta.com/oauth2/default \
-e SCS_MCP_SERVER_URL=https://your-server.example.com \
-e SCS_MCP_OAUTH_REQUIRED_SCOPES=openid \
simianhacker/semantic-code-search-mcp-server
Required scopes
SCS_MCP_OAUTH_REQUIRED_SCOPES controls which scopes the server advertises and requires on every token. The minimum recommended value for Okta is openid. Setting it to an empty string causes Okta to reject the authorization request with a "no scopes configured" error.
Note: scopes like offline_access and email work with Okta and the major IDEs but are not guaranteed by any standard. Avoid them if you need M2M (client credentials) access.
Local development without OAuth
When SCS_MCP_SERVER_URL is not set (or points to localhost), the server binds to 127.0.0.1 only. Set SCS_MCP_SERVER_URL to a non-localhost URL to bind to all interfaces (required for Docker containers and reverse proxy deployments).
Restricting access to specific OAuth clients
By default, any token issued by the configured authorization server is accepted. To restrict access to a specific app:
SCS_MCP_OAUTH_ALLOWED_CLIENT_IDS=0oa1abc123def456gh78 # space-separated for multiple IDs
This is recommended when multiple OAuth apps share the same authorization server (common in Okta). Without it, tokens from any app in the tenant that targets the same audience will be accepted. The server checks the client_id, azp, or cid (Okta-specific) claim in the JWT, whichever is present.
Checking your auth status
When OAuth is enabled, an auth_status tool is available in all MCP clients. Ask the AI assistant to call it:
"Call the auth_status tool"
It returns your client ID, granted scopes, and token expiry — nothing sensitive (the token itself is never included).
Token lifetime
Clients re-authenticate when their access token expires. To reduce auth prompts, increase the access token lifetime in your authorization server. For Okta: Admin → Security → API → Authorization Servers → default → Access Policies.
Configuration
Configuration is managed via environment variables in a .env file.
| Variable | Description | Default |
|---|---|---|
ELASTICSEARCH_CLOUD_ID |
The Cloud ID for your Elastic Cloud instance. | |
ELASTICSEARCH_API_KEY |
An API key for Elasticsearch authentication. | |
ELASTICSEARCH_INDEX |
The name of the Elasticsearch index to use. | semantic-code-search |
SCS_MCP_OAUTH_ENABLED |
Enable OAuth 2.0 bearer token authentication (HTTP mode only). | false |
SCS_MCP_OAUTH_ISSUER |
OIDC issuer URL. Required when SCS_MCP_OAUTH_ENABLED=true. |
|
SCS_MCP_OAUTH_AUDIENCE |
Expected aud claim override. Use for Okta non-URL audiences (e.g. api://default). |
|
SCS_MCP_OAUTH_REQUIRED_SCOPES |
Space-separated scopes the server requires on every token. Minimum openid for Okta. |
|
SCS_MCP_OAUTH_ALLOWED_CLIENT_IDS |
Space-separated allowlist of OAuth client IDs. Empty = any client from the issuer. | |
SCS_MCP_OAUTH_CLIENT_ID |
Client ID for token introspection (opt-in). Requires SCS_MCP_OAUTH_CLIENT_SECRET. |
|
SCS_MCP_OAUTH_CLIENT_SECRET |
Client secret for token introspection (opt-in). | |
SCS_MCP_SERVER_URL |
Public URL of the server. Required for OAuth and non-localhost deployments. |
Semantic Code Search MCP questions
What tools does Semantic Code Search MCP provide?
It exposes 6 tools, including semantic_code_search, map_symbols_by_query, symbol_analysis, read_file_from_chunks, document_symbols.
How can I run the server using Docker?
You can run it in HTTP mode by pulling the image from Docker Hub and setting the ELASTICSEARCH_ENDPOINT environment variable.
Does the server support OAuth 2.0?
Yes, the HTTP mode supports OAuth 2.0 bearer token authentication using an OIDC-compliant authorization server.