Sourcegraph Codex Plugin

An Agent Plugin that wires Sourcegraph's MCP server into Codex. Giving Codex disciplined code search, navigation, history, and Deep Search over your Sourcegraph-indexed repositories.

What's in here

plugin.json     # Agent Plugins manifest
mcp.json        # Declares the "sourcegraph" streamable-http MCP server
skills/
  searching-sourcegraph/
    SKILL.md                    # Tool-selection logic, scoping rules, workflows
    query-patterns.md           # Regex query reference by language/intent
    examples/common-searches.md # Worked search examples
    workflows/
      implementing-feature.md
      understanding-code.md
      debugging-issue.md
      fixing-bug.md
      code-review.md

The searching-sourcegraph skill teaches Codex when to reach for code_finder vs keyword_search vs nls_search vs deepsearch, how to scope queries with repo:/file: filters, and gives step-by-step workflows for common engineering tasks (implementing a feature, debugging, fixing a bug, reviewing a PR).

Tools exposed

Tool	Purpose
code_finder	Agentic search — describe what you want, it finds candidate files/lines
keyword_search	Exact-pattern / regex search
nls_search	Natural-language / semantic search
find_references	Trace symbol usage
go_to_definition	Jump to implementation
read_file / list_files	Read and browse repo contents
list_repos	Find repositories
commit_search / diff_search / compare_revisions	History and change tracking
deepsearch / deepsearch_read	Multi-step research jobs over the codebase
get_contributor_repos	Find repos a given user has worked on
evaluator	Sandboxed Lua aggregation over search results (counts, joins, filters)

code_finder, evaluator, and deepsearch require the /.api/mcp/all endpoint — see Known limitations.

Installation

Install through Codex's plugin manager, or copy this directory into your Codex plugins location and point Codex at it.

Configuration

The plugin talks to your own Sourcegraph instance's MCP endpoint. mcp.json currently declares:

{
  "mcpServers": {
    "sourcegraph": {
      "type": "streamable-http",
      "url": "${SOURCEGRAPH_ENDPOINT}/.api/mcp/all"
    }
  }
}

${SOURCEGRAPH_ENDPOINT} is not yet functional — see below. Once resolved, it should point at your Sourcegraph instance (e.g. https://sourcegraph.example.com or https://sourcegraph.com).

Authentication is expected to happen via OAuth: Sourcegraph's MCP server supports OAuth 2.0 Dynamic Client Registration, and Codex owns/injects the Authorization header for MCP connections itself, so no access token needs to be configured in this plugin.

Known limitations

The Agent Plugins v1 spec does not allow ${VAR}-style expansion in a streamable-http/sse server's url (only ${PLUGIN_ROOT}/${PLUGIN_DATA} are expanded, and only for stdio servers' args/env/cwd). Codex's implementation enforces this and substituting ${SOURCEGRAPH_ENDPOINT} fails URL validation