PowerOffice MCP for Codex

A local MCP server for secure access from Codex to the PowerOffice Go API v2 with read-only and explicitly confirmed write operations. The server works with the DEMO API, uses OAuth 2.0 Client Credentials, and provides small, explicitly limited tools instead of a generic HTTP proxy.

What is already available

• poweroffice_configuration_status — checks whether configuration exists without exposing key values.

• poweroffice_connection_info — checks the connection and returns available integrations/privileges.

• poweroffice_search_customers — searches customers with filters and pagination.

• poweroffice_get_customer — gets a single customer by numeric ID.

• poweroffice_list_general_ledger_accounts — reads the chart of accounts.

• poweroffice_list_account_transactions — reads transactions for a required date range.

• poweroffice_create_customer — creates a customer after confirm=true.

• poweroffice_update_customer — applies an allowed JSON Patch to a customer after confirm=true.

• poweroffice_create_general_ledger_account — creates an account after confirm=true.

• poweroffice_update_general_ledger_account — applies an allowed JSON Patch to an account after confirm=true.

Read tools remain read-only. Write tools modify data only with an explicit confirm=true; deleting, posting, and sending documents are not part of this stage.

Related MCP server: SceneBoard MCP for Codex

Requirements

• Node.js 22 or newer

• pnpm 11

• PowerOffice application key, client key, and subscription key

• the access roles needed for the endpoints being called

Installation

pnpm install
cp .env.example .env.local
pnpm build
pnpm test

Fill in .env.local locally:

PO_ENV=demo
PO_APPLICATION_KEY=...
PO_CLIENT_KEY=...
PO_SUBSCRIPTION_KEY=...
PO_USER_AGENT=poweroffice-mcp/0.1 your-email@example.com

.env.local is excluded from Git. Do not send keys in chat and do not add them to .codex/config.toml.

Connecting to Codex

The project file .codex/config.toml already launches the built dist/index.js via STDIO. It reads .env.local if the file exists, and can also receive the listed variables from the Codex process environment.

After pnpm build, restart the Codex task for this project. Start by calling poweroffice_configuration_status, then poweroffice_connection_info.

Local development

pnpm dev
pnpm typecheck
pnpm test
pnpm build
pnpm smoke

The server writes only MCP messages to stdout; startup errors go to stderr. Tokens are cached with a margin before expiration; on 401 one token refresh is performed, and on 429 up to two retries with a delay of at least one second for read requests. Write requests are not retried automatically to avoid duplicates. The overall request rate is limited by the PO_MAX_REQUESTS_PER_SECOND value and cannot exceed 10.

Environment variables

For production, switch PO_ENV=production; the token and API URLs are selected by code, not entered by the user.

MVP boundaries

• Only the PowerOffice API v2 and the STDIO transport.

• No webhooks, automatic paging through all pages, or operations for deleting, posting, and sending documents.

• Write tools are limited to Customers and GeneralLedgerAccounts and require confirm=true.

• The Fields field can be overridden, but by default the server requests compact data sets.

• The next page is always requested explicitly via pageNumber; the X-Pagination header metadata is returned together with the result.

Documentation: PowerOffice Developer Portal, MCP in Codex.