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.
What the MCP integration is designed to support
| Capability | Current behavior |
|---|---|
| Transport | stdio child-process MCP servers. |
| Config import | .penter/mcp.json and .cursor/mcp.json from the open workspace. |
| Manual config | Server name, command, args and optional working directory from Extensions. |
| Discovery | List the tools exposed by a connected server when MCP execution becomes available. |
| Tool execution | Not available in the packaged public beta. Future releases will require approval. |
| Remote HTTP/SSE MCP | Not part of the current PENTER MCP transport; use a local stdio launcher/bridge if your integration provides one. |
mcpServers object with command/args/cwd/env and imports.cursor/mcp.json, but the current runtime executes stdio servers.Quick start from the Extensions view
- 1Open a workspaceWorkspace-relative imports and cwd resolution need an active workspace path.
- 2Open Extensions / PluginsUse “MCP server” to add one manually or “Import mcp.json” to read workspace config.
- 3Add or import the serverFor manual setup provide a server name, executable command, arguments and optional working directory.
- 4ConnectPENTER shows an approval request before it starts the MCP child process.
- 5Verify tool discoveryAfter initialization the server card reports its connected state and discovered tool count.
- 6Use from an agentThe agent can list servers/tools and request mcp.call. Every call is approval-gated.
Configure .penter/mcp.json or .cursor/mcp.json
{
"mcpServers": {
"example": {
"command": "node",
"args": ["tools/example-mcp/server.mjs"],
"cwd": ".",
"env": {
"EXAMPLE_TOKEN": "${env:EXAMPLE_TOKEN}"
}
}
}
}| Field | Meaning | Notes |
|---|---|---|
| mcpServers.<name> | Named server entry. | The object key becomes the display name/import source for the server id. |
| command | Executable or launcher. | Required. Examples: node, npx, python, uvx, a native binary. |
| args | Argument array. | Imported only when values are strings. Manual UI also accepts a JSON array or space-separated args. |
| cwd | Working directory. | “.” or empty resolves to the current PENTER workspace. Relative paths resolve under the workspace. |
| env | Environment overrides. | String values only. Imported env values are intentionally not persisted to renderer localStorage. |
.penter/mcp.json first, then .cursor/mcp.json. Keep the intended configuration in one clear place to avoid confusion.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.
"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.
.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.What happens when you connect
- 1PENTER validates the server configServer id/name/command/args/cwd/env are schema checked before process startup.
- 2Desktop requests operator approvalThe approval binding describes starting the configured MCP command.
- 3Electron main spawns the processstdin/stdout/stderr are piped. On Windows, shell mode is used so npm/npx .cmd launchers work after approval.
- 4PENTER sends initializeThe client sends JSON-RPC initialize with the MCP protocol version and client info.
- 5PENTER sends notifications/initializedAfter the server responds, the normal MCP initialized notification is sent.
- 6PENTER requests tools/listTool name, description and input schema are cached for the connected server.
- 7The server becomes available to agentsmcp.listServers and mcp.listTools can now expose the connected capabilities.
How agents use MCP
| Agent tool | Purpose | Approval |
|---|---|---|
| mcp.listServers | List currently connected MCP servers. | Read-only; no tool execution. |
| mcp.listTools | Refresh/list tools exposed by one connected server. | Read-only discovery. |
| mcp.call | Call a specific server tool with a JSON arguments object. | Explicit operator approval required for each call. |
mcp.listServers
→ mcp.listTools({ serverId: "example" })
→ mcp.call({ serverId: "example", toolName: "echo", arguments: { text: "hello" } })
→ operator approval
→ tools/call resultIf the requested tool is missing from the cached server tool list, PENTER refreshes tools/listbefore rejecting it as unknown.
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.
Troubleshoot MCP connections
.penter/mcp.json or .cursor/mcp.json under that workspace.tools/list, writes JSON-RPC to stdout, and does not print banners/log lines to stdout.${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.Ready to get started?
Follow the setup guide, install the current approved Desktop release, and connect your account.