Semantic 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>_locations stores one document per chunk occurrence (file path + line ranges + directory/git metadata) and references chunks by chunk_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-resource from 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.