MCP sessions and security

Setup authorizes a dedicated session for an existing Nord owner and account. A profile stores the network, owner, selected account, session identity, authoritative expiry and renewal deadline, and a credential-store reference. Network and owner changes require another profile.

Browser authorization

nord-mcp setup --profile personal --method browser --network devnet

Connect an external Solana wallet that controls the Nord owner, select an account in the terminal if prompted, review the session details, and sign the message in your wallet. Supply --account-id to select a known account during setup. Wait for the CLI to verify authorization before using the profile.

The temporary approval page runs on loopback and closes after completion, cancellation, or ten minutes. Keep its single-use URL private. The browser returns only the owner public key and signature; the session secret remains in the CLI. Email/Turnkey login and hardware-wallet transaction-signing fallbacks are not supported.

For a headless host, forward the port printed by setup to the same port on your local machine, then open the printed URL in your wallet-enabled browser. For example, replace 54321 and host below with your setup port and SSH host:

ssh -N -L 54321:127.0.0.1:54321 host

Owner keyfile authorization

Use a Solana JSON keypair file through the setup CLI:

nord-mcp setup --profile headless --method keyfile \
  --network devnet --owner-keyfile /private/path/owner.json --storage file

Setup displays the authorization and asks for confirmation. Owner key material and its path are not saved as runtime profile configuration. Never paste a private key into an agent conversation or pass a raw key as a command argument or tool input.

Credential authority and storage

Nord session keys permit more than the MCP trading tools, including transfers and withdrawals. Account selection and omitted tools are local package boundaries, not protocol-enforced restrictions. Someone with the session secret can use it outside this package. Use a dedicated account with funds appropriate to that authority.

OS credential storage is the default. Linux requires a supported, unlocked credential-store backend. An unavailable backend produces an error and does not silently fall back to files.

Use --storage file explicitly for hosts without a credential store. File mode stores plaintext credentials in owner-only files and private directories; the package does not encrypt them. Unsafe ownership, permissions, and symlink paths are rejected.

Profiles and request journals are stored outside the source repository:

• macOS: ~/Library/Application Support/nord-mcp
• Linux: $XDG_CONFIG_HOME/nord-mcp, or ~/.config/nord-mcp when unset
• Override: NORD_MCP_CONFIG_HOME

Protect this directory and preserve request history when recovering interrupted operations. Never commit credentials or setup URLs to source control.

Session lifetime

A session has a 24-hour lease, with renewal bounded by a seven-day authorization deadline. The server checks at startup and hourly, renewing when fewer than 12 hours remain. It does not renew an expired session or extend beyond the verified deadline. Run setup again after expiry or the end of the authorization window.

Interrupted setup preserves pending state and checks the exact session public key on Nord before another authorization. Re-run setup with the same profile to recover; do not discard its pending state. Replacement verifies and activates the new session before attempting to revoke the previous one. If that revocation cannot be verified, the old session remains recorded and another replacement is blocked until access is resolved.

Manage sessions and requests

Only one process may hold a profile at a time. While an agent is connected, use nord_get_connection and nord_get_request to inspect readiness and requests. Stop that profile's serving process before CLI commands that access or change it, including status, request inspection, setup, renewal, revocation, and removal. This also applies when a client automatically restarts its server.

nord-mcp profiles list
nord-mcp status --profile personal
nord-mcp requests list --profile personal
nord-mcp requests inspect order-example-001 --profile personal
nord-mcp renew --profile personal

An ambiguous renewal is reconciled before another attempt. For an unresolved trade, follow request recovery.

To stop session access, revoke it and wait for remote verification:

nord-mcp revoke --profile personal

Then remove the local profile if it is no longer needed:

nord-mcp profiles remove personal

Revocation checks Nord before reporting success and covers a recorded previous session when one remains. Local removal deletes the profile and credentials, but retains request history and reports any unverified remote access. Removing local files alone does not prove remote revocation.

Neither revocation nor removal cancels outstanding orders. Handle open orders separately before retiring a trading profile.

Troubleshooting

Symptom	Next step
Executable not found by a desktop client	Configure the absolute path from command -v nord-mcp and confirm Node.js is available to the client
No compatible wallet detected	Open the setup URL in a browser with a Wallet Standard wallet that supports Solana message signing
Setup link unavailable or expired	Check the CLI result, then restart setup with the same profile if it did not complete
No Nord account found	Create and fund the account outside the MCP package, then retry after Nord processes it
Profile in use	Stop the other serving process, or use separate profiles for simultaneous clients
Session expired or revoked	Run setup again; expired sessions cannot be renewed
Stale RFQ pricing	Wait for fresh reference data and retry the preview; do not infer a fill from a placement acknowledgement
Unknown execution outcome	Inspect the original request ID; do not submit a replacement with a new ID