PenterDocumentationMCP integrations
Documentation

MCP integrations

Understand MCP extensions and how to prepare integrations for future supported PENTER releases. Server startup and tool calls remain disabled in the packaged public beta.

Packaged beta: MCP execution is disabled
The packaged Windows public beta currently blocks MCP server start and tool execution while scope and outbound-connection controls are being verified. The setup reference below applies to compatible development/future builds and does not bypass the release restriction.
01

What the MCP integration is designed to support

CapabilityCurrent behavior
Transportstdio child-process MCP servers.
Config import.penter/mcp.json and .cursor/mcp.json from the open workspace.
Manual configServer name, command, args and optional working directory from Extensions.
DiscoveryList the tools exposed by a connected server when MCP execution becomes available.
Tool executionNot available in the packaged public beta. Future releases will require approval.
Remote HTTP/SSE MCPNot part of the current PENTER MCP transport; use a local stdio launcher/bridge if your integration provides one.
Cursor-compatible means config shape, not every Cursor transport feature
PENTER accepts the common mcpServers object with command/args/cwd/env and imports.cursor/mcp.json, but the current runtime executes stdio servers.
02

Quick start from the Extensions view

  1. 1
    Open a workspace
    Workspace-relative imports and cwd resolution need an active workspace path.
  2. 2
    Open Extensions / Plugins
    Use “MCP server” to add one manually or “Import mcp.json” to read workspace config.
  3. 3
    Add or import the server
    For manual setup provide a server name, executable command, arguments and optional working directory.
  4. 4
    Connect
    PENTER shows an approval request before it starts the MCP child process.
  5. 5
    Verify tool discovery
    After initialization the server card reports its connected state and discovered tool count.
  6. 6
    Use from an agent
    The agent can list servers/tools and request mcp.call. Every call is approval-gated.
03

Configure .penter/mcp.json or .cursor/mcp.json

Workspace MCP config
{
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["tools/example-mcp/server.mjs"],
      "cwd": ".",
      "env": {
        "EXAMPLE_TOKEN": "${env:EXAMPLE_TOKEN}"
      }
    }
  }
}
FieldMeaningNotes
mcpServers.<name>Named server entry.The object key becomes the display name/import source for the server id.
commandExecutable or launcher.Required. Examples: node, npx, python, uvx, a native binary.
argsArgument array.Imported only when values are strings. Manual UI also accepts a JSON array or space-separated args.
cwdWorking directory.“.” or empty resolves to the current PENTER workspace. Relative paths resolve under the workspace.
envEnvironment overrides.String values only. Imported env values are intentionally not persisted to renderer localStorage.
The import button stops at the first readable compatible config
PENTER checks .penter/mcp.json first, then .cursor/mcp.json. Keep the intended configuration in one clear place to avoid confusion.
04

Environment variables and secrets

The spawned MCP process receives the parent process environment plus the server-specific env object. PENTER also expands values written as ${env:NAME} from the current process environment before spawn.

Recommended secret reference
"env": {
  "API_TOKEN": "${env:MY_REAL_API_TOKEN}"
}
  • Prefer environment references or session-entered values over literal API keys committed to the workspace.
  • Imported MCP env values are available for the current session but are removed from the persisted renderer extension state.
  • Non-secret server configuration such as command, args and cwd can persist so the server is easy to reconnect later.
  • Remember that the child process inherits the broader PENTER process environment too.
Memory-only in PENTER does not make a literal secret safe in Git
If you put a real token directly in .cursor/mcp.json or .penter/mcp.json, the file itself can still leak it. Use environment references and keep secret-bearing config out of version control.
05

What happens when you connect

  1. 1
    PENTER validates the server config
    Server id/name/command/args/cwd/env are schema checked before process startup.
  2. 2
    Desktop requests operator approval
    The approval binding describes starting the configured MCP command.
  3. 3
    Electron main spawns the process
    stdin/stdout/stderr are piped. On Windows, shell mode is used so npm/npx .cmd launchers work after approval.
  4. 4
    PENTER sends initialize
    The client sends JSON-RPC initialize with the MCP protocol version and client info.
  5. 5
    PENTER sends notifications/initialized
    After the server responds, the normal MCP initialized notification is sent.
  6. 6
    PENTER requests tools/list
    Tool name, description and input schema are cached for the connected server.
  7. 7
    The server becomes available to agents
    mcp.listServers and mcp.listTools can now expose the connected capabilities.
stdout is the protocol channel
PENTER reads newline-delimited JSON-RPC messages from stdout. Non-JSON stdout lines are ignored. Put diagnostics on stderr so they do not interfere with protocol traffic; PENTER drains stderr to prevent a noisy server from blocking.
06

How agents use MCP

Agent toolPurposeApproval
mcp.listServersList currently connected MCP servers.Read-only; no tool execution.
mcp.listToolsRefresh/list tools exposed by one connected server.Read-only discovery.
mcp.callCall a specific server tool with a JSON arguments object.Explicit operator approval required for each call.
Typical agent flow
mcp.listServers
→ mcp.listTools({ serverId: "example" })
→ mcp.call({ serverId: "example", toolName: "echo", arguments: { text: "hello" } })
→ operator approval
→ tools/call result

If the requested tool is missing from the cached server tool list, PENTER refreshes tools/listbefore rejecting it as unknown.

07

MCP security model

PENTER treats MCP as executable capability, not as inherently trusted context. A configured server can run code with the privileges of the local user and can expose tools that perform external actions, so the process boundary and approval flow are intentional.

  • Starting a server requires operator approval.
  • Every mcp.call requires operator approval.
  • Server processes run in Electron main, not the renderer UI process.
  • Imported env values are not persisted in renderer localStorage.
  • Disconnecting/removing a server terminates the managed child process; app shutdown also tears down connected MCP processes.
  • MCP does not create authorization for a target. You still need legitimate engagement scope for any security-related tool the server exposes.
08

Troubleshoot MCP connections

PENTER says no mcp.json was found.
Open a workspace first and place the file at .penter/mcp.json or .cursor/mcp.json under that workspace.
The server starts in a terminal but not in PENTER.
Check the exact command, working directory and PATH visible to the desktop process. On Windows, verify the launcher is available without relying on a shell profile that only your terminal loads.
The server connects but shows zero tools.
Verify the server implements MCP tools/list, writes JSON-RPC to stdout, and does not print banners/log lines to stdout.
A tool call says unknown tool.
PENTER refreshes the tool list once before failing. Confirm the server exposes the same exact tool name and that dynamic tool registration has completed.
A call times out.
PENTER allows up to 120 seconds for a tools/call request. Long-running work should either return earlier with a job handle or be implemented with an architecture that does not block one MCP call indefinitely.
My env variable is empty.
If using ${env:NAME}, make sure NAME exists in the environment inherited by PENTER Desktop. A variable in an unrelated terminal session is not automatically available to an already-running desktop process.
PENTER ignores text my server prints.
That is expected for non-JSON stdout. Protocol messages belong on stdout; human diagnostics should go to stderr.
Next step

Ready to get started?

Follow the setup guide, install the current approved Desktop release, and connect your account.