MCP and Runtime

MCP and Runtime

AgentDesk supports MCP import, readiness review, live discovery, and tool calls through the packaged loopback runtime.

Supported MCP Config Shapes

AgentDesk can import common MCP config shapes:

• Claude-style mcpServers
• VS Code-style servers
• nested mcp.servers
• remote server URL definitions
• single-server JSON

Example files:

• docs/examples/mcp-claude-desktop.json
• docs/examples/mcp-vscode.json

Import Flow

1. Open the MCP tab.
2. Paste a config.
3. Click import.
4. Review readiness, risk flags, env/header key names, and inferred tool hints.
5. Add MCP nodes if the imported servers match your workflow.

Import does not automatically execute MCP servers. It is metadata and readiness review first.

Runtime Discovery

Live MCP discovery requires Runtime mode through the packaged CLI.

npx --yes --package=@papaplus/agentdesk agentdesk --port 5173

Then:

1. Open Doctor.
2. Click Check runtime.
3. Open MCP.
4. Import config.
5. Click Discover for a selected server.

Official MCP SDK Adapter

AgentDesk uses the official @modelcontextprotocol/sdk stdio adapter by default inside the existing loopback runtime boundary.

The legacy JSON-RPC client remains available for comparison or fallback:

AGENTDESK_MCP_ADAPTER=legacy-jsonrpc agentdesk --port 5173

The adapter boundary preserves:

• loopback-only runtime API
• explicit user action
• timeouts
• output caps
• redacted artifacts
• no automatic remote probing

Remote Streamable HTTP MCP

Remote MCP URLs are probed only after explicit discovery. AgentDesk negotiates the MCP protocol version and preserves session metadata where available.

Remote probing is still not a production trust boundary. Review every endpoint before probing it, and avoid sending secrets unless you understand the server and transport.

Local Command Nodes

Local command nodes are intended for local developer workflows and controlled demos.

Runtime behavior includes:

• command and args come from node config
• cwd is resolved conservatively
• output is capped
• stderr and stdout are redacted
• command timeouts are enforced

Do not connect local command nodes to destructive commands unless you fully understand the effect.

Runtime Profiles

Runtime profiles store approved runtime metadata locally. They include:

• command
• args
• cwd
• server id
• env/header key names
• readiness state

They do not store secret values.

Practical Debugging Checklist

If MCP discovery fails:

1. Confirm the runtime CLI is running.
2. Confirm you are using Runtime mode.
3. Confirm the imported config still contains the target server id.
4. Confirm the server command is installed and on PATH.
5. Check whether the server writes non-JSON logs to stdout.
6. Check stderr artifact output in AgentDesk.
7. Try the legacy adapter only if you suspect SDK compatibility behavior.