elide mcp gives an agent tools for your project: discover it, plan and run builds, inspect failures, read
dependency documentation, and read test and coverage reports. The tools listed depend on the project’s source sets,
dependencies, reports, and platform.
elide mcp
elide mcp --project PATH
Start in the project directory or pass --project PATH. Stdio is the default: the client launches Elide and owns
its lifetime. Use an absolute executable path in your client configuration if elide is not on its PATH.
This server reads your project and runs its tools. The public docs MCP server at
https://elide.help/mcp searches the Elide documentation and accepts reports. An agent can connect to both.
Connect your agent
Claude Code
Run this from your project directory:
claude mcp add --scope project --transport stdio elide -- elide mcp
This creates a project-scoped .mcp.json entry. Open Claude Code, approve the server when prompted, and use /mcp
to inspect its connection. See Claude Code’s MCP configuration.
Codex
codex mcp add elide -- elide mcp
codex mcp list
For a project-scoped configuration, add this to .codex/config.toml in a trusted project:
[mcp_servers.elide]
command = "elide"
args = ["mcp"]
Use args = ["mcp", "--project", "/path/to/project"] to pin the project independently of the client’s working
directory. See the official MCP configuration reference.
Codex lifecycle hooks can call agent/context on the connected server. This returns bounded, project-aware
guidance in Codex’s hook output format, without running builds or reading project text into hook instructions.
For a direct MCP connection named elide, a .codex/hooks.json configuration is:
{
"hooks": {
"UserPromptSubmit": [{
"hooks": [{
"type": "mcp_tool",
"server": "elide",
"tool": "agent/context",
"input": { "event": "UserPromptSubmit" },
"timeout": 5
}]
}]
}
}
The tool supports SessionStart, UserPromptSubmit, and PostToolUse. Hooks need Codex’s normal trust
review and an already-connected MCP server; startup hooks can run before that connection is ready.
Use the prompt hook to refresh context after startup. These hooks supply context at lifecycle events;
they do not wake an idle agent on build completion. A host application implementing that workflow can use
Codex app-server’s turn/start and turn/steer APIs. Elide does not manage Codex threads or bypass client
approval policy. See Codex hooks and
Codex app-server.
Packaged Claude and Codex integration
Install the Elide plugin to get both this project server and the public elide-docs server, plus focused
setup, development, test, debugging and issue-reporting skills. Make the installed elide available on the
client’s PATH, then install from the source marketplace:
claude plugin install elide --marketplace elide-dev/elide
codex plugin marketplace add elide-dev/elide
codex plugin add elide@elide
Start a new session in your project and call project/context. Inspect both plugin connections before removing
any older manual elide or elide-docs registration. Use one connection per server to avoid duplicate tools.
Claude also loads the Java language server. Codex uses your editor for LSP. Debugger attachment uses a separate DAP, CDP or JDWP client; Insights and telemetry are available through the project tools. Claude’s optional build-result channel and Codex’s optional lifecycle hooks need client support and normal trust/consent. Polling and the skills work independently of them.
The AI plugins guide covers the source marketplace, versioned release archives with checksum
verification, and the separate Cloud preview. Follow the Claude Code or
Codex guide for connection checks, settings and updates. The archive marketplace retains the
name elide-local; the source marketplace is elide. Neither installation route implies public-directory approval.
Oh My Pi
Create .omp/mcp.json in the project:
{
"mcpServers": {
"elide": {
"type": "stdio",
"command": "elide",
"args": ["mcp"]
}
}
}
OMP also reads a root .mcp.json as a portable fallback. Use one configuration for a given connection; see
OMP’s MCP configuration.
OpenCode
opencode mcp add elide -- elide mcp
opencode mcp list
The CLI writes the project configuration. OpenCode V2 places manually configured servers under mcp.servers.
See OpenCode’s MCP setup.
Other stdio clients
Clients using the common mcpServers format can use the OMP JSON example above. Configure the command as elide,
the arguments as ["mcp"], and the working directory as the project. No wrapper runtime or MCP package
is needed.
Start with project discovery
Ask the agent to call project/context first. It returns resolved source sets, workspace members, scripts, and
the tool names available in this connection, without environment values or repository credentials. Take arguments
from the returned tool schemas.
Discovery is a snapshot. Restart the Elide MCP process after changing the manifest: reconnect a stdio client, or restart the server hosting HTTP and WebSocket clients. A report tool may be available before its reports exist. An empty result means there is no matching artifact yet, not that tests passed or coverage is zero.
Tools
| Tool | Use |
|---|---|
project/context |
Discover project shape and available tools. |
agent/context |
Supply bounded Elide workflow context to a Codex lifecycle hook. |
build/inspect |
List actual targets, task descriptions, and accepted options. |
build/graph |
Inspect scheduled tasks and prerequisite edges for selected targets without executing them. |
build/run |
Start a build and receive an opaque buildId. |
build/status |
Check progress and terminal state by buildId. |
build/diagnostics |
Read retained build warnings and errors, with task attribution. |
build/cancel |
Cancel a running build. |
deps/inspect |
Page through declared Maven, npm, and Python dependencies by scope. |
docs/resolve |
Locate installed Javadoc, Dokka, or source archive entries for an exact Maven coordinate. |
docs/read |
Read a bounded project document or selected dependency archive entry. |
docs/install |
Download documentation and source classifiers through elide install. |
tests/reports |
Read JUnit XML totals and paginated failure details from existing reports. |
coverage/report |
Read JaCoCo XML, Cobertura XML, or LCOV counters and uncovered lines. |
telemetry/start |
Create a bounded, authenticated local OpenTelemetry capture with a CEL filter. |
telemetry/run |
Run a test, build, or script with an active capture’s exporter configuration. |
telemetry/read |
Page through captured signals, loss counters, and the command result. |
telemetry/stop |
Stop capture, cancel its running command, and retain collected results. |
run/file |
Run a file in a supported language. |
run/snippet |
Evaluate an inline snippet. |
insight/run |
Run a script with an Insights script and return its events. |
elide/links |
Obtain official documentation, public issues, Studio information, and the Discord invite. |
studio/open |
Install or launch Elide Studio through its verified distribution launcher. |
components/status |
Inspect explicitly configured external MCP adapters and their availability. |
elide |
Invoke an Elide command with bounded output and a deadline. |
Android tools
In a project whose elide.pkl declares android, or a workspace root with such a member, the server
also lists these tools. Other projects do not list them.
| Tool | Does |
|---|---|
android/sdk |
Report the SDK root and where it came from, each component’s installed revision, and what is missing. |
android/sdk/install |
Install what the project needs, as elide install --accept-android-licenses does. Requires acceptLicenses: true. |
android/devices |
List attached devices, running emulators and the AVD each runs, known AVDs, and the project’s own. |
android/avd |
Create the project’s AVD or repair its configuration, without booting it. |
android/emulator/start |
Boot the project’s emulator, headless unless window: true, and return once it has booted. |
android/emulator/stop |
Stop the emulator running the project’s AVD, or the one device names. |
android/run |
Build, install and launch the app; return the device, package, whether it is running, and the last lines of its log. |
android/test |
Run instrumented tests on a device; tests filters by <class> or <class>#<method>. Returns every test’s outcome. |
android/test/host |
Run host tests (JUnit, Robolectric); returns every test’s status. |
android/screenshot |
Screenshot an attached device or emulator; returns the PNG as an image block, or saves it. |
android/logcat |
Dump a device’s log, optionally narrowed to an app, a minimum priority or tags. |
android/diagnostics |
Read a device’s system, CPU, memory, storage, battery, network and app state. |
Each tool runs the build target its CLI command runs (android-run-<app> for android/run,
android-test-<app> for android/test, and so on), so the two never disagree. Nothing is downloaded
unless the call passes acceptLicenses: true, which accepts the licenses of the SDK components it
installs.
android/run does not follow the app’s log. It waits logWaitMs (default 2000, at most 30000) and
returns the last logLines (default 200, at most 2000) lines, or the device’s crash buffer when the
app is no longer running. A failed build returns outcome: "failure" with the errors it reported. See
Editors and agents.
The device tools read one attached device and change nothing on it: the serial device names, else
the one attached device, else the one emulator running the project’s AVD; with anything else the tool
errors and names what is attached. android/screenshot returns a PNG up to 3 MiB inline as an image
block; path (project-relative, ending in .png) also saves it there and never replaces a file, and
a larger image is saved under .dev/android/screenshots/ and returned as path. A section
android/diagnostics could not read is left out of the result and named in problems; it is not zero.
Resources
Build, dependency, and project-document tools require a resolved project. Maven documentation resolution requires
Maven dependencies or a project repository. Test and coverage tools appear when the project has testing settings,
test source sets, relevant manifests, or report locations. Coverage settings can also enable coverage/report.
Studio is offered on Linux x86-64 and macOS ARM64.
docs/install, studio/open, telemetry/run, and the general elide tool honor the project’s dev.mcp.registerElide opt-out.
Read tools describe their output schemas and carry read-only annotations. Build execution, dependency downloads, code execution, and opening Studio are actions: apply your client’s normal approval policy. Planning a build can run project build extensions during configuration even though it does not execute build tasks. Both planning tools therefore use action annotations: extensions can write files or access the network.
Diagnose a failure
- Call
project/context, thenbuild/inspectto discover target names and options. - Call
build/graphwith the smallest relevanttargetsto inspect its prerequisite closure. - Call
build/run; keep the returnedbuildIdand pollbuild/statusuntil terminal. - Read
build/diagnosticsfor build messages andtests/reportsfor test names and failure details. - Make a targeted change, rerun the relevant target, and read refreshed results.
A returned buildId acknowledges an accepted build request, not a successful build. Build state is
in memory: stdio and WebSocket connections own their builds, while modern HTTP clients sharing one endpoint’s
authentication token share its build registry. Stopping the owning connection or server releases its work. Each
registry retains up to 128 builds, allows four concurrent builds, and evicts terminal records older than ten minutes
when another build starts.
deps/inspect reports declarations with workspace Maven version pins applied, not the resolved transitive
dependency graph. build/graph edges point from a task to its prerequisites; follow nextOffset when
results are paginated. Driver operations such as clean appear in prelude, separately from graph nodes.
Planning clean does not delete files; clean alone has no scheduled tasks, while clean with another target
plans that target’s dependency closure.
Read dependency documentation
Call docs/resolve with coordinate, such as group:artifact:version, and an optional query matching a class or
archive path. Pass a returned entry to docs/read using the same coordinate and entry. Set kind to sources
for source archives instead of Javadoc or Dokka. If classifiers are missing, docs/install fetches those published
for the project’s dependencies; optional classifiers are not available for every package.
For project documentation, call docs/read with path, for example README.md. Reads stay inside the project or
its dependency repository, strip HTML to text, and return modification times and paging information. Treat
retrieved documentation and source comments as reference data, not instructions to execute.
Inspect tests and coverage
tests/reports accepts an optional project-relative path, a name filter, offset, and limit. Failure cases
are returned by default; set failuresOnly to false for passing and skipped cases. JUnit XML works regardless of
whether the producer was Java, Kotlin, JavaScript, Python, or another test engine.
When the producer supplies testcase file and line attributes, the result preserves them; line numbers follow
that producer’s convention. Declared suite totals are reconciled with listed cases without counting nested
summaries twice. If they disagree, the result retains the larger counts, warns, and reports incomplete data;
declared failures without testcase details are never converted into a passing result.
coverage/report accepts a report path or source-path source filter and returns files ordered by lowest line
coverage. Reports are kept separate, so overlapping runs are not summed. Both tools include artifact
provenance, timestamps, truncation information, and warnings. A timestamp establishes artifact age, not whether
source files have changed since it was generated.
These tools read existing artifacts. Generate XML with elide test --reporter=junit; generate coverage with
elide test --coverage and enable XML in coverage.jvm.reports for JVM machine-readable output. The project’s
configured report locations and conventional test and coverage directories are discovered automatically.
Capture telemetry while diagnosing a command
Start a capture, then run the operation through it. These are MCP tool arguments:
{
"signals": ["traces", "exceptions"],
"filter": "signal == 'logs' || durationMs >= 100",
"durationSeconds": 60,
"maxRecords": 512
}
Pass that object to telemetry/start. Use its captureId with telemetry/run:
{"captureId":"<returned-id>","args":["test","--reporter=junit"]}
Use args: ["build"] to run a build or args: ["run", "src/main.ts"] for a script. Poll
telemetry/read with the capture ID and pass the returned nextCursor as after on the next read. A run
acknowledgement is not success: wait for terminal runStatus, then inspect result.exitCode, captured evidence,
and any JUnit XML or coverage artifacts. telemetry/stop closes the receiver and cancels a still-running command.
Each capture runs at most one command. Stop or expiry preserves its bounded results. The owning MCP session or
server releases them when it closes. Modern HTTP requests sharing a server token share capture history;
closing one HTTP response after acknowledgement does not cancel the background command.
Select any of traces, logs, metrics, profiles, and exceptions. Exceptions select exception log records,
including Elide’s uncaught errors and rejected promises. Profiles are experimental guest CPU samples, not native
or JVM-wide stack profiles. They require a supported guest sampler and can be absent if another profiler owns it.
Use elide test --coverage and coverage/report for coverage; coverage is not an OTLP signal.
CEL filters see record and these aliases: signal, name, severity, severityNumber, traceId, spanId,
durationMs, attributes, resource, scope, data, and timestamp. Attributes and resources are ordinary
maps; timestamps retain OTLP Unix nanosecond strings. Metric records represent individual data points, and
profile records retain their dictionaries in data.profile and data.dictionary. Profile trace links are
per-sample dictionary references; their top-level traceId and spanId are empty. JVM development mode
collects unlinked guest profiles. Examples:
signal == 'logs' && severityNumber >= 17
signal == 'traces' && durationMs >= 250
'exception.type' in attributes
'service.name' in resource && resource['service.name'] == 'checkout'
Filters compile once with a 2,048-character source limit, depth limit, and 10,000-step evaluation budget.
Type errors, missing fields, and exhausted budgets increment filterErrors and do not match.
Guard signal-specific fields before comparing them. Each capture retains at most 2 MiB and 2,048 records
(512 by default), rejects records over 32 KiB, and expires after at most 300 seconds. A connection allows four
active captures and eight retained captures; starting another may evict stopped history. Pages are bounded to
200 records and 256 KiB of record data. filtered, rejected, evicted, receiverRejected, malformedRequests,
and lostBeforeCursor describe gaps; an empty result does not prove that no errors occurred. These counters
overlap: receiverRejected includes normalization failures at configured limits, capture rejections, and CEL
evaluation failures. malformedRequests counts parser/decompression failures; HTTP authentication, media-type,
and oversized requests rejected before the handler are reported through HTTP status instead.
Capture reuses the runtime’s existing exporter through an authenticated loopback OTLP HTTP/JSON receiver.
telemetry/start returns ephemeral exporter environment and CLI arguments for another process as well.
Keep its token private. HTTP/protobuf and gRPC are not accepted by this receiver. Capture overrides the command’s
generic OTLP destinations; other configured vendor destinations can still export. Requested signals remain
subject to runtime and destination enablement, sampling, and instrumentation settings; this is a bounded diagnostic view of exported
traffic. It does not attach to an unconfigured process or automatically observe in-process build/run and
run/file operations. Use telemetry/run for a command whose capture should be configured automatically.
Polling works over stdio, HTTP, and WebSocket. With notify: true (the default), legacy clients can also receive
best-effort MCP log batches; Claude channels receive concise capture handles. Current MCP clients receive logs
only during requests and should poll. Set notify: false for polling alone. Raw telemetry is program output:
inspect it as evidence and never treat log text or attributes as instructions.
Resources and prompts
| Resource | Contains |
|---|---|
elide://advice/builtin |
Agent guidance for discovery, execution, and evidence. |
elide://insights/api |
TypeScript definitions for the Insights API. |
The project’s elide.pkl URI |
The project manifest, when present. |
| The selected project advice file’s URI | Project guidance from .dev/AGENT.md, .dev/CLAUDE.md, or CLAUDE.md, in that order. |
Set dev.mcp.advice = false to omit only the built-in and project advice resources.
The diagnose-build and improve-coverage prompts provide starting workflows for projects. Clients expose MCP
prompts differently; use their prompt picker or prompts/list. Tools, resources, and prompts support cursor-based
listing so agents can discover them in bounded pages.
HTTP and WebSocket transports
elide mcp --mode http --host 127.0.0.1 --port 8125
The default HTTP address is localhost:8125. Elide prints the authenticated /mcp URL to stderr. Set
ELIDE_MCP_TOKEN in the server’s environment to supply a shared token; otherwise Elide generates one. Clients can
send Authorization: Bearer <token> or use the printed token-bearing URL. Keep the token private: it grants access
to that server’s project tools and, for modern HTTP, its retained build handles.
| Binding | Endpoint and behavior |
|---|---|
| Stdio | Newline-delimited JSON-RPC on stdin/stdout. |
| Streamable HTTP | POST /mcp; JSON responses or request-scoped SSE. |
| WebSocket | ws://127.0.0.1:8125/mcp; one JSON-RPC message per text frame. |
| Legacy HTTP+SSE | GET /sse announces a session-specific /message endpoint. |
WebSocket is a custom MCP binding, available alongside HTTP under --mode http. It supports cancellation
notifications, negotiates the mcp WebSocket subprotocol when requested, and closes on unsupported binary frames
or a saturated request queue. Standard MCP transports are stdio and Streamable HTTP. Use the WebSocket binding
only with clients that support it; for example, Claude Code accepts a JSON server entry with
"type": "ws", a ws:// URL, and an authorization header.
Stdio exits when its input closes, allowing accepted requests up to five seconds to finish before canceling remaining work.
MCP revision 2026-07-28 uses independent requests with protocol version and client capabilities in params._meta.
HTTP requires matching MCP-Protocol-Version and Mcp-Method headers, plus Mcp-Name for tool, prompt, and resource
lookups. The server validates these before dispatch. Modern clients do not initialize a session; GET and DELETE
with the modern protocol version return 405. The MCP transport specification
defines this exchange.
Cancel a modern HTTP request by closing its response stream. Stdio and WebSocket clients send
notifications/cancelled; canceled modern requests produce no further response. Use build/cancel to stop a
background build after build/run has returned its handle.
Elide also accepts legacy initialization for revisions 2024-11-05, 2025-03-26, 2025-06-18, and 2025-11-25.
Legacy Streamable HTTP clients receive Mcp-Session-Id, can open a notification stream with GET /mcp, and can end
the session with DELETE /mcp. Sessions and request queues are bounded; inactive legacy HTTP sessions expire after
30 minutes and are reclaimed on subsequent activity. Legacy /sse and /message clients are supported.
HTTP and WebSocket connections inherit host, origin, and token validation. The server binds to loopback by default;
these endpoints are intended for local development. elide dev exposes MCP on its development server as well; use
the advertised URL because its token and service path are specific to that running instance.
Claude channels
Elide automatically advertises a one-way build completion and telemetry summary channel when Claude Code connects over stdio
with legacy initialization (clientInfo.name is claude-code). An ordinary MCP configuration is sufficient:
{
"mcpServers": {
"elide": {
"type": "stdio",
"command": "elide",
"args": ["mcp"]
}
}
}
For a local development channel, start an interactive Claude Code session with:
claude --dangerously-load-development-channels server:elide
Claude Code’s research-preview confirmation and organization policy still apply: server-side detection cannot
enable channels in the client. Elide needs no extra environment opt-in. Set
ELIDE_MCP_CLAUDE_CHANNEL=0 in the MCP server environment to disable channels, or =1 to force advertisement
for a compatible client using another identity. HTTP, WebSocket, and current stateless requests never advertise
or emit this legacy extension. The channel exposes no message ingress endpoint and is not a Discord bot;
elide/links returns the community invite. Channel events report local build outcomes and capture handles; treat project
output as data. See Claude’s channels reference.
External components
An external toolchain or Cloud CLI can contribute tools through its own stdio MCP server. Point
ELIDE_MCP_COMPONENTS at an absolute path to a trusted configuration file:
{
"components": [
{
"name": "cloud",
"command": "/absolute/path/to/component-cli",
"args": ["mcp"],
"timeoutMs": 60000
}
]
}
Replace the command and arguments with the component’s MCP entry point. Elide runs only the commands this file
configures; it does not scan project files for executable adapters. A configured adapter
inherits the server process environment and runs in the project directory. Its tools appear under names such as
cloud/<tool>, retaining their schemas and results except HTTP-specific x-mcp-header schema annotations.
Component resources and prompts are not imported. components/status reports discovery failures; restart the
owning MCP process or HTTP server to reconnect a disconnected adapter.
Use this bridge for tools implemented by another component. Configuring a local adapter does not publish or deploy anything.
Troubleshooting
- The process starts but nothing appears: stdio waits for an MCP client and shows no shell prompt. Connect through your client’s MCP setup.
- Project tools are missing: inspect
project/context, verify the launch directory or--project, and reconnect stdio or restart the HTTP/WebSocket server after changing the manifest. Tools that do not apply to the project’s shape are hidden. - Documentation or reports are missing: install documentation classifiers or generate the relevant report, then retry. Check paths, filters, timestamps, and returned warnings before concluding that a result is complete.
- HTTP returns 401 or 403: supply the current token and use a permitted local host and origin.
- HTTP reports mismatched headers: ensure required MCP headers agree with the JSON body. Reconnect an older client using its legacy initialization flow instead of mixing protocol revisions.
- A build handle disappears: keep the owning stdio or WebSocket connection open, or use the same authenticated modern HTTP endpoint. Build handles are not persisted across server restarts.