Persona Machine MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
persona-machine-mcp
Unofficial. Not affiliated with or endorsed by Persona (withpersona.com). MIT licensed.
A stdio MCP server that connects Hermes, Claude Code, Claude Desktop, Cursor, Codex CLI, or any other MCP host to Persona MCP Server V2, using a machine client rather than a browser login. Requires Python 3.10+; runtime uses the MCP Python SDK 1.x, not 2.x.
A Persona machine client is an OAuth application registered with a public key. The bridge signs
short-lived private_key_jwt assertions and exchanges them with client_credentials. Persona
access tokens live about 15 minutes and have no refresh token. This bridge caches tokens only
in memory, re-mints 90 seconds before expiry, and re-mints/retries once after an upstream 401.
The MCP host sees an ordinary stdio server; it does not store or refresh bearer tokens.
Why a bridge exists
MCP hosts authenticate to remote servers in one of two ways: a static header (an API key or a bearer pasted into the config, read once at startup) or the browser OAuth flow from the MCP authorization spec (authorization code + PKCE, a person signs in, the host stores a refresh token). Neither fits a Persona machine client:
A machine-client access token (
puat_…) expires after ~15 minutes and comes with no refresh token. A static header therefore works for one quarter of an hour and then every call returns 401. There is nothing for the host to "refresh": getting a new token means signing a brand-newprivate_key_jwtclient assertion with your private key and exchanging it withgrant_type=client_credentials. No mainstream host (Hermes, Claude Code, Claude Desktop, Cursor, Codex CLI) implements that grant or that re-minting loop.The browser OAuth flow is person-bound: it needs someone to sign in, inherits that person's session, and cannot run under a gateway, a cron job or a CI runner. Persona's MCP V2 also does not offer dynamic client registration for arbitrary hosts, so generic host OAuth clients are rejected at the consent step.
So the token lifecycle has to live somewhere between the host and Persona. This package is that
somewhere: a tiny stdio MCP server that the host launches like any other local server. It keeps
the private key, signs assertions, mints the short-lived token, re-mints it 90 seconds before
expiry, retries once on a 401, and proxies tools/resources/prompts to https://withpersona.com/mcp
unchanged. The host never sees a bearer, never has to rotate anything, and keeps working unattended.
It was first written as a one-file script to get a Hermes gateway talking to Persona with no human
in the loop, and packaged so any MCP host can reuse it.
Related MCP server: Latchkey
Quickstart
Install uv and ensure uvx is on your
host application's PATH.
Until the first PyPI release, run straight from GitHub by replacing every
uvx persona-machine-mcp below with:
uvx --from git+https://github.com/anpicasso/persona-machine-mcp persona-machine-mcp(pin a tag or commit with @v0.1.0 / @<sha> for reproducibility). From a local checkout use
uv sync and uv run persona-machine-mcp.
uvx persona-machine-mcp keygenThis creates an EC P-256 keypair under ~/.config/persona-machine-mcp (or
$XDG_CONFIG_HOME/persona-machine-mcp) and prints the public PEM. Private key: mode 0600;
public key: mode 0644. Never share the private key.
In Persona Dashboard → API Keys → Machine clients, create a client and paste the public PEM. Choose minimal scopes. Use a dedicated Dashboard user: the machine client inherits that user's role, and changes to or deletion of that user can affect access. Then save the exact issued id:
uvx persona-machine-mcp configure --client-id oac_YOUR_CLIENT_ID
uvx persona-machine-mcp checkcheck authenticates, initializes MCP, and prints OK: <n> tools (<filtered>/<total>) followed by
the visible tool names. The first number and numerator both count exposed tools after filtering.
No command means serve; stdout then carries only MCP protocol messages. All logs go to stderr.
Runbook for AI agents
This section is written for an agent (Hermes, Claude Code, Codex, Cursor agent mode, …) that has been asked to set this bridge up. Follow the steps in order; each has an expected result and a stop condition. Do not improvise around a failed step.
Ground rules
Never print, paste, log or commit the private key (
private.pem), the client assertion, or the output oftoken. The only secret you are allowed to show the human is nothing; the only key material you show is the public PEM printed bykeygen.Never edit the host's config file by hand when the host has a CLI for MCP servers (Hermes refuses agent edits to
config.yaml; usehermes mcp add).Steps marked HUMAN require a person with Persona Dashboard access. Stop and hand off; do not try to automate the Dashboard.
Replace
uvx persona-machine-mcpwithuvx --from git+https://github.com/anpicasso/persona-machine-mcp@<tag-or-sha> persona-machine-mcpuntil the package is on PyPI (see Quickstart). The<tag-or-sha>should be a reviewed commit.
Step 0 — preconditions
uv --version && uvx --version # need uv; Python 3.10+ is provisioned by uv automatically
uvx persona-machine-mcp --version # expected: a version string, e.g. 0.1.0If uv is missing, install it from https://docs.astral.sh/uv/getting-started/installation/ (ask
the human if installation needs privileges). Stop if --version does not run.
Step 1 — decide the configuration home
Default: ~/.config/persona-machine-mcp (or $XDG_CONFIG_HOME/persona-machine-mcp). Use a
dedicated directory per environment/identity (--home /path or PERSONA_MCP_HOME) when the host
runs under a service account or several Persona clients will coexist. Record the chosen path; every
later command must use the same --home/PERSONA_MCP_HOME.
Step 2 — generate the key pair
uvx persona-machine-mcp keygen # EC P-256 (default) — preferred
# or: uvx persona-machine-mcp keygen --alg rsa --bits 2048Expected: stdout contains exactly one -----BEGIN PUBLIC KEY----- … -----END PUBLIC KEY-----
block; stderr says where private.pem (0600) and public.pem (0644) were written. If keygen
exits 1 with "exists", a key is already there: do not use --force unless the human confirms
rotation (it destroys the old key). Capture the public PEM for the next step.
Step 3 — HUMAN: register the machine client in Persona
Hand the public PEM to the human with these instructions: Persona Dashboard → API Keys →
Machine clients → Create; paste the public PEM (EC P-256 or RSA ≥ 2048 is accepted); pick
the minimal scopes needed (read scopes such as inquiry:read, inquiry_template:read,
account:read, verification:read, case:read, environment:read; only add writes like
inquiry.create:write, inquiry:write, case:write when required); confirm with the Dashboard
password; copy the issued client id, which starts with oac_. Recommend a dedicated Dashboard
user for the registration, because the client inherits that user's role and dies with it.
Wait for the human to return the oac_… id. Do not guess or reuse ids.
Step 4 — save the client id
uvx persona-machine-mcp configure --client-id oac_XXXXXXXXExpected: prints the path of <home>/client_id (mode 0600). Exit 1 means the id does not start
with oac_ or contains whitespace: re-check what the human sent.
Step 5 — verify authentication
uvx persona-machine-mcp checkInterpret the exit code:
0andOK: <n> tools (<n>/<total>)→ setup complete. Continue.2(invalid_client) → the id or the registered public key does not match. Confirm with the human that the PEM pasted is the onekeygenprinted and that the id is the one issued for it.3(invalid_grant) → clock skew or assertion rejected. Check system time (NTP), then retry.4→ token endpoint/network failure. Check outbound HTTPS towithpersona.com, then retry.5→ authenticated but the MCP upstream failed to initialize. Retry once; if it persists, report with the stderr lines (they are already redacted of secrets).1→ configuration: runuvx persona-machine-mcp pathsand confirmkeyandclient_idresolve to the files you created (sourcesfile, or the env/flag you intended).
Optionally narrow the surface before wiring the host, and re-run check with the same filters:
uvx persona-machine-mcp check --tools 'list_inquir*' --tools 'show_*'Step 6 — register the MCP server in the host
Use the host's own command. Pass the same --home (or set PERSONA_MCP_HOME in the server's
env block) and the same filters you validated in step 5.
# Hermes (writes mcp_servers.persona into the active profile's config.yaml; interactive prompts:
# answer y to overwrite an existing entry, Y to enable all tools, or "select" to pick)
hermes mcp add persona --command uvx --connect-timeout 120 --args persona-machine-mcp
hermes mcp test persona # expected: "Connected" and "Tools discovered: <n>"
hermes config set mcp_servers.persona.enabled true
# Claude Code
claude mcp add persona -- uvx persona-machine-mcp
# Codex CLI
codex mcp add persona -- uvx persona-machine-mcpFor Claude Desktop / Cursor, merge the JSON block from MCP hosts. When the home is
not the default, add "env": {"PERSONA_MCP_HOME": "/path"} (Hermes: --env PERSONA_MCP_HOME=/path).
Expected: the host lists the persona server with the tool count from step 5. A host that only
starts the server on launch needs a restart/reload (Hermes: new session or /reload-mcp).
Step 7 — install the agent skill (optional, recommended)
The skill teaches the agent setup, rotation and troubleshooting boundaries. It is not part of
the MCP protocol and is installed separately; the same SKILL.md follows the cross-vendor Agent
Skills format.
# Hermes: install straight from the repository (pin the same tag/sha you used for the bridge)
hermes skills install https://raw.githubusercontent.com/anpicasso/persona-machine-mcp/<tag-or-sha>/agent-plugin/skills/persona-machine-mcp/SKILL.md
# Claude Code: personal skills directory
mkdir -p ~/.claude/skills/persona-machine-mcp
curl -fsSL https://raw.githubusercontent.com/anpicasso/persona-machine-mcp/<tag-or-sha>/agent-plugin/skills/persona-machine-mcp/SKILL.md \
-o ~/.claude/skills/persona-machine-mcp/SKILL.md
# Other hosts: copy agent-plugin/skills/persona-machine-mcp/SKILL.md into the host's skills directoryAlternative for Hermes only: install the whole agent-plugin/ directory as a portable plugin (see
Hermes Agent Plugin); it brings the MCP entry and the skill, but must
not coexist with a manual persona entry from step 6.
Step 8 — report
Report to the human: configuration home, key algorithm, that the public PEM was registered, the
tool count from check, the host command used, filters applied, and the skill location. Do not
include the client id in chat unless the human asks; never include key or token material.
Rotation (later): generate into a new home (keygen --dir <new>), have the human register the
new public key and issue a new id, configure --home <new>, check --home <new>, switch the host
to the new home, then ask the human to revoke the old client. In-place keygen --force only with
explicit confirmation.
Limits
These tokens work with MCP V2 (
https://withpersona.com/mcp) and the Persona CLI API. They are not documented for general REST/api/v1access. The OAuth token endpoint itself is under/api/v1/oauth/token; that does not make the resulting token a REST API key.Machine clients cannot approve or decline inquiries via MCP, regardless of scopes.
Persona limits machine-client writes to approximately 20 writes/minute. Handle limits in the host; this bridge does not automatically replay write calls except its single HTTP 401 retry.
Persona roles/scopes remain authoritative. A local tool filter is not server-side authorization.
No MCP V1/API-key mode, HTTP listener, registration automation, or write-path helpers in v0.1.
MCP hosts
Complete setup first, and make uvx available in each host's execution environment. For a
non-default configuration directory, pass --home /absolute/path or set PERSONA_MCP_HOME.
Hermes
hermes mcp add persona --command uvx --args persona-machine-mcp
hermes mcp test personaRestart/reload the host after registering. See the Hermes MCP documentation.
Claude Code
claude mcp add persona -- uvx persona-machine-mcpClaude Desktop / Cursor
Merge into the host's MCP configuration; uvx must be discoverable by the GUI process:
{
"mcpServers": {
"persona": {
"command": "uvx",
"args": ["persona-machine-mcp"]
}
}
}Codex CLI
codex mcp add persona -- uvx persona-machine-mcpEquivalent ~/.codex/config.toml entry:
[mcp_servers.persona]
command = "uvx"
args = ["persona-machine-mcp"]Pin the argument to persona-machine-mcp==<version> (PyPI) or --from git+https://github.com/anpicasso/persona-machine-mcp@<tag-or-sha> where reproducibility is important.
Hermes Agent Plugin
The portable Agent Plugins v1 package is agent-plugin/, not this repository's root. It
bundles the persona MCP entry (currently uvx --from git+…@main, switching to a PyPI pin after
the first release) and a setup/rotation skill. From a reviewed
checkout, with a fresh destination:
# HERMES_HOME must point to the intended profile if you use named profiles.
install -d "${HERMES_HOME:-$HOME/.hermes}/plugins"
cp -R ./agent-plugin "${HERMES_HOME:-$HOME/.hermes}/plugins/persona-machine-mcp"
hermes plugins list
hermes plugins enable persona-machine-mcpThis documented local-directory installation avoids assuming that hermes plugins install
selects a nested plugin automatically. See plugin setup and the
Hermes plugin guide.
Do not enable both the plugin and the manual persona MCP entry; the manual config takes
precedence. This copied installation is updated manually.
Configuration
Flags may appear before or after the command. Precedence is flag > environment > home file. No shell interpolation is performed on values; quote glob patterns to prevent shell expansion.
Flag | Environment | Home file / default |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Unset: client defaults |
|
| All tools |
|
| None excluded |
|
|
|
Legacy PERSONA_CLIENT_ID_FILE overrides the path used for file-based client-id resolution.
The normal path is <home>/client_id, not next to an externally configured key; when migrating
an older standalone bridge, set this legacy variable explicitly if your id is next to that key.
configure always writes <home>/client_id with mode 0600; remove a stale legacy override when
switching to the new home. PERSONA_PRIVATE_KEY_PEM wins over the environment path, but never
over --key. Files must contain an unencrypted private PEM (PKCS#8 output is generated).
EC must be P-256; RSA must be at least 2048 bits. Other keys are rejected.
Commands
# Default command is serve (stdio).
uvx persona-machine-mcp serve
# RSA is optional; default keygen is EC P-256.
uvx persona-machine-mcp keygen --alg rsa --bits 3072 --dir /secure/persona
# Paths and winning sources only: no client-id value, PEM or token.
uvx persona-machine-mcp paths
# Public JWKS. Default kid is the RFC 7638 SHA-256 thumbprint.
uvx persona-machine-mcp jwks
uvx persona-machine-mcp jwks --kid rotation-2
# Intentionally prints a secret to stdout. Do not log or paste the result.
uvx persona-machine-mcp token
uvx persona-machine-mcp token --no-resource
uvx persona-machine-mcp token --resource https://withpersona.com/mcp --scope 'inquiry:read'
uvx persona-machine-mcp --version
uvx persona-machine-mcp --helptoken defaults its resource to the resolved MCP URL. --no-resource omits that form field.
With no client id, serve warns and connects unauthenticated, for offline/local testing;
check and token require credentials. Real Persona will not accept unauthenticated requests.
Bad credentials are rejected eagerly, before the stdio server opens.
Tool filtering
uvx persona-machine-mcp serve --tools 'list_inquir*' --tools 'show_*' --exclude-tools '*secret*'
uvx persona-machine-mcp check --tools 'list_inquir*' --tools 'show_*'An allow match is required when an allow-list exists; deny matches win afterward. Environment
forms are comma-separated, for example PERSONA_MCP_TOOLS='list_inquir*,show_*'. Filters apply
to check, discovery and invocation: calling a hidden tool returns tool not exposed by this bridge.
Tool listing follows all upstream cursor pages. Resources/prompts are exposed only when the
upstream advertises those capabilities; they are not affected by tool-name filtering.
Exit codes
Code | Meaning |
0 | Success (or clean Ctrl-C shutdown) |
1 | Usage/configuration error: missing key, invalid PEM, invalid |
2 | Token endpoint |
3 | Token endpoint |
4 | Other token endpoint failure: HTTP status, malformed response, network |
5 | Upstream MCP connection/initialization or unexpected bridge failure |
Diagnostics omit token endpoint response bodies, assertions and access tokens. invalid_client
and invalid_grant are classified by structured error fields, never by provider message text.
Security and rotation
Keep private keys and the client-id file at
0600, outside source control. Public PEMs are0644. Permission guarantees target POSIX; on Windows, also restrict access with filesystem ACLs.Never commit keys, copy them into an MCP/plugin manifest, or log the output of
token. The.gitignoreexcludes PEM files,.envandclient_id; that is defense in depth, not a vault.Only register public PEM/JWKS. The generated JWKS contains no private parameters.
Use minimal Persona scopes and a dedicated Dashboard user. Treat MCP write calls as real operations; the bridge neither adds approvals nor grants permission to act.
Custom token and MCP endpoints receive assertions/bearers. Use trusted HTTPS endpoints outside local tests; do not send real credentials to a diagnostic mock server.
For in-place rotation: stop the host's bridge, run
keygen --force, re-register the new public key in Persona, save the replacement client id withconfigure, runcheck, then restart.--forcedestroys the previous local key. Without it, either existing key file blocks keygen.For a safer cutover, generate/configure/check a separate
--home(orkeygen --dir) and then switch the host to that home. Revoke the old client after the replacement works. Protect and eventually remove old private keys according to your retention policy.
Development and release
uv sync --frozen
uv run pytest -q
uv run ruff check .
uv run python -X dev -m pytest -q
uv build
uvx --from ./dist/persona_machine_mcp-*.whl persona-machine-mcp --versionTests mint against httpx.MockTransport and exercise a real stdio bridge subprocess against a
loopback FastMCP/uvicorn upstream. They need no Persona account or internet service. Dependency
installation itself may require internet access. CI tests Python 3.10–3.14 with the committed
uv.lock and builds an sdist and wheel.
Before tagging v0.1.0, configure a PyPI trusted publisher for owner anpicasso, repository
persona-machine-mcp, workflow publish.yml, and environment pypi. Configure GitHub's
pypi environment with required reviewers if approval is desired. A pushed v* tag triggers the
publish workflow, verifies the tag equals the package version, runs tests/lint, builds, and
publishes using OIDC (id-token: write), without a long-lived PyPI token. Nothing is published by
local build/test commands.
Roadmap: v0.2 — --http PORT. Not implemented in this release.
Author: Angello Picasso. MIT license.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA self-hosted bridge that exposes local stdio MCP servers to ChatGPT and Claude over HTTPS with OAuth, providing a secure passthrough for your own tools.1MIT
- AlicenseNot gradedqualityBmaintenancePuts a single OAuth 2.1 authorization gateway in front of self-hosted MCP servers, letting Claude.ai and other OIDC-backed clients sign users in and receive tokens scoped to one person and one service. Wraps stdio or Streamable HTTP upstreams behind one hostname with a path per service, with allowlisted redirects, hashed stored tokens, and per-tool audit lines.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables secure cross-system identity and token exchange for autonomous agents, including on-behalf-of token exchange, scoped permission delegation, token lifetime refresh, and zero-leakage ephemeral credentials. It integrates with MCP-compatible clients via standard JSON-RPC stdio without external runtime dependencies.7MIT
- AlicenseNot gradedqualityCmaintenanceBridges remote MCP clients such as ChatGPT connectors, Codex, and other MCP agents to a local DSH Relay MCP endpoint by providing an OAuth 2.1 authorization server plus a tool allowlist proxy that works behind a Cloudflare Tunnel. It exposes a controlled subset of relay tools (with added session archiving and permission reconciliation) so remote clients can list workspaces, dispatch read-only or writable runs, and monitor or steer them on the local machine.MIT