MCP¶
Let any MCP-capable AI agent (Copilot, Claude, Cursor, ...) query the calls captured by KtorMonitor. Read-only, debug-time, works on Android, iOS, Desktop and Web.
The app connects out to the companion, so it also works in browsers and on iOS.
Quick setup checklist¶
Do these in order. Every step is required unless marked optional.
- App: add the
ktor-monitor-mcpdependency (step 1). - App: call
KtorMonitor.MCP.start()once at startup, in debug builds only (step 1). - Machine: download the companion JAR (step 2).
- AI client: register the JAR as an MCP server and restart the client (step 3).
- Android/iOS only: make the app able to reach
127.0.0.1:2991(see Connectivity). - Verify: run the app, then ask the AI to call
list_apps(step 4).
Prerequisites
Ktor Monitor itself (ktor-monitor-logging, -okhttp-interceptor or -http4k-filter) must already be
installed, otherwise there are no calls to query. Java 11+ must be on the PATH of the machine running the AI client.
1. Add the module to your app (debug only)¶
Dependency (replace <version> with the Ktor Monitor version, e.g. 1.18.1):
// Android module
debugImplementation("ro.cosminmihu.ktor:ktor-monitor-mcp:<version>")
releaseImplementation("ro.cosminmihu.ktor:ktor-monitor-mcp-no-op:<version>")
For a Kotlin Multiplatform module without build types, add it to commonMain (or the target source set you need)
and only call start from debug code:
kotlin.sourceSets.commonMain.dependencies {
implementation("ro.cosminmihu.ktor:ktor-monitor-mcp:<version>")
}
Start it once, as early as possible (e.g. Application.onCreate, main(), or where you create the HttpClient).
It does nothing unless you call it:
import ro.cosminmihu.ktor.monitor.KtorMonitor
KtorMonitor.MCP.start()
// or with options (these are the defaults):
KtorMonitor.MCP.start {
host = "127.0.0.1"
port = 2991
token = null // shared secret, must match the companion (optional)
appName = null // name shown by list_apps (optional, but recommended)
}
Set appName
appName is optional, but set it (e.g. appName = "MyApp"). Without it the app shows up as just its
platform name, so with several apps or projects connected you cannot tell them apart in list_apps.
KtorMonitor.MCP.status exposes the connection state (Stopped, Connecting, Connected, Rejected).
The list header shows a blinking AI badge while connected and a static red AI! when the companion
rejected the connection (wrong token, or different library and companion versions). Nothing is shown while
connecting or stopped.
2. Download the companion¶
The companion is the MCP server your AI client starts. It is a single JAR (Java 11+):
VERSION=1.18.1 # same as the library version
mkdir -p ~/.ktor-monitor
curl -L -o ~/.ktor-monitor/ktor-monitor-mcp-companion-all.jar \
"https://repo1.maven.org/maven2/ro/cosminmihu/ktor/ktor-monitor-mcp-companion/$VERSION/ktor-monitor-mcp-companion-$VERSION-all.jar"
Warning
Use the -all JAR (fat jar) and keep its version equal to the ktor-monitor-mcp library version,
otherwise the app is rejected (red AI! badge).
Use an absolute path in the client config (no ~ or $HOME; most clients do not expand them),
e.g. /Users/you/.ktor-monitor/ktor-monitor-mcp-companion-all.jar.
3. Register the companion in your AI client¶
Clients that support local stdio servers launch the JAR themselves; you never run it manually.
The server name is ktor-monitor.
For a project-specific server, add .mcp.json at the repository root. To share the
configuration with collaborators, commit it as .github/mcp.json instead:
{
"mcpServers": {
"ktor-monitor": {
"type": "stdio",
"command": "java",
"args": ["-jar", "/absolute/path/ktor-monitor-mcp-companion-all.jar"]
}
}
}
Copilot CLI loads project-level configs only for trusted repositories. The .vscode/mcp.json
format is not read by Copilot CLI.
For a user-wide server instead, add the same entry to ~/.copilot/mcp-config.json or run
/mcp add in the CLI.
For a project/workspace-specific server, add .vscode/mcp.json to the workspace. Its key is
servers (not mcpServers):
{
"servers": {
"ktor-monitor": {
"type": "stdio",
"command": "java",
"args": ["-jar", "/absolute/path/ktor-monitor-mcp-companion-all.jar"]
}
}
}
You can also use the repository-root .mcp.json from the Copilot CLI example above; VS Code
forwards eligible servers from that portable format to Copilot Chat. The .vscode/mcp.json
format is specific to VS Code and is not read by Copilot CLI.
For a project-shared server, run this from the project directory; Claude Code writes it to
.mcp.json:
claude mcp add --scope project --transport stdio ktor-monitor -- \
java -jar /absolute/path/ktor-monitor-mcp-companion-all.jar
For a personal server available across projects, use --scope user instead of
--scope project.
Add the server in Claude Desktop's MCP settings (or edit its claude_desktop_config.json).
This is a user-level configuration; Claude Desktop does not use Claude Code's project
.mcp.json.
For a project-specific server, add .cursor/mcp.json to the project. Commit it to share the
configuration with collaborators. Cursor also reads ~/.cursor/mcp.json for user-wide
servers; the project config takes precedence when server names conflict.
MCP servers are configured under Settings > Tools > AI > MCP Servers and stored in
Android Studio's configuration directory, not in a project-level file. Android Studio's MCP
integration currently does not support stdio, so it cannot launch the Ktor Monitor companion
JAR directly.
Restart the client (or reload MCP servers) after editing the config.
Options (optional): --port / KTOR_MONITOR_MCP_PORT (default 2991), --token / KTOR_MONITOR_MCP_TOKEN
(must match token in the app config). Add them to args, or use "env": { "KTOR_MONITOR_MCP_TOKEN": "..." }
to keep the token out of the process list. The server only listens on 127.0.0.1.
Several projects at once
Only one companion can listen on a port. If the port is busy (e.g. another project's companion),
the companion automatically uses the next free one, up to 9 ports after the configured one, and logs it.
The app connects to every companion in that range, so no manual port is needed. Note that the app is then
visible to the AI client of each companion running on the same machine.
On Android, run adb reverse for the range (e.g. tcp:2991 to tcp:3000).
4. Verify it works¶
- Start the app (debug build). The list header should show the blinking AI badge once the AI client has launched the companion.
- Ask the AI: "Use ktor-monitor
list_apps". It should return your app. Then "List the last 10 calls". - If it is empty, make some HTTP requests in the app first.
5. Connectivity¶
| Platform | Notes |
|---|---|
| Desktop / Web | 127.0.0.1 works as is. |
| Android emulator/device | adb reverse tcp:2991 tcp:2991 (emulator can also use 10.0.2.2). Needs cleartext traffic allowed in debug. |
| iOS simulator | Add NSAppTransportSecurity > NSAllowsLocalNetworking = true to Info.plist. |
Troubleshooting¶
| Symptom | Fix |
|---|---|
| AI client shows the server as failed / no tools | Check java -version is 11+, the JAR path is absolute and is the -all JAR. Companion logs go to stderr prefixed with [ktor-monitor-mcp] (see the client's MCP log). |
list_apps returns nothing |
The app is not connected: it did not call KtorMonitor.MCP.start(), is a release build (no-op), or cannot reach the host/port (see Connectivity). |
Red AI! badge / Rejected |
token differs between app and companion, or library and companion versions differ. |
| Port already in use | Handled automatically (next free port, up to 9 more). If all are busy, stop old companions or change --port and the app port. |
| Android: connection fails | Run adb reverse tcp:2991 tcp:2991, allow cleartext in debug, add INTERNET permission. |
Tools¶
list_apps, list_calls, get_call, search_calls, get_stats (all accept an optional app_id).
Arguments are validated against the tool schema (types and ranges, e.g. limit 1..200, max_body_length up to 256000); invalid input is returned to the AI as a tool error so it can retry.
list_calls/search_calls paginate with offset / next_offset; bodies are truncated by max_body_length.
Security notes¶
- Headers are masked by your
sanitizeHeaderconfig at capture time, so the AI sees the same masked values as the UI. - Bodies are not sanitized. Do not enable MCP when traffic contains data you don't want an AI to read.
- Set a
token(and pass the same value with--tokenorKTOR_MONITOR_MCP_TOKEN, which keeps it out of the process list). The token is never sent over the socket: app and companion prove they know it with a challenge/response (HMAC-SHA256), so a process that grabs the port first can neither learn the token nor read your traffic. Without a token, any local process can pose as an app or read the calls, only web pages are blocked. - Responses are bounded (max 4 concurrent queries per app, bodies capped at 256000 characters) and the companion cancels the work in the app when a request times out.
- The MCP server is a small hand-written JSON-RPC implementation (protocol versions 2025-06-18, 2025-03-26, 2024-11-05).