Portal.io API MCP

A local, read-only MCP server for a Portal.io account. It signs API requests with Portal's HMAC-SHA256 scheme and makes account data available to Codex through structured tools.

Included tools

• test_connection: confirm the current credentials can make a read-only request.
• list_proposals and get_proposal: browse proposal summaries and details.
• list_users: look up Portal salesperson IDs.
• search_contacts: find contacts in the Portal account.
• search_catalog: search account catalog items when Catalog API access is enabled.

Version 0.1.0 contains no mutation tools. It cannot create, update, archive, or send anything in Portal.

Install

git clone https://github.com/AWfusion/portal-api-mcp.git
cd portal-api-mcp
npm ci
cp .env.example .env

Fill in .env with credentials from the same Portal environment:

PORTAL_ENV=sandbox
PORTAL_BASE_URL=https://sandbox.api.portal.io
PORTAL_APP_ID=your-api-application-key
PORTAL_SECRET_KEY=your-secret-key
PORTAL_USER_API_KEY=the-meta-apiKey-value-from-the-credential-exchange
PORTAL_WRITE_ENABLED=false

For production, use PORTAL_ENV=production and PORTAL_BASE_URL=https://api.portal.io only when Portal has issued and enabled production credentials for the integration.

PORTAL_USER_API_KEY must be the exact meta.apiKey returned by GET /authenticate/apikeyexchange. Do not substitute the application ID, secret key, a Portal UI token, or the username/password used for the one-time exchange. Portal's returned User API Key is Base64-encoded and is normally 44 characters long.

The actual .env file is ignored by Git. Keep its permissions owner-only:

chmod 600 .env

Verify

npm test
npm run verify

npm run verify performs a local MCP initialization, confirms every tool is registered, and makes one read-only GET /public/proposals?PageNumber=1&PageSize=1 call. It outputs no credentials.

Register Globally in Codex

Run the included installer from the project directory:

./scripts/install-codex-mcp.sh

It registers this local process globally under the name portal-api. Confirm it with:

codex mcp get portal-api

Restart Codex or open a new task after registration so the tools are discovered. Typical requests include “list my most recently modified Portal proposals” and “search the catalog for Denon receivers.”

Troubleshooting

• app id could not be found: the API application ID is not enabled for the selected base URL. Sandbox credentials belong at https://sandbox.api.portal.io; production credentials belong at https://api.portal.io.
• request signature (hash) is invalid: first confirm PORTAL_USER_API_KEY is the Base64 meta.apiKey returned by the credential exchange, then confirm the app ID, secret, and User API Key all came from the same environment.
• Catalog queries return authorization errors: ask Portal to enable Catalog API access for the account.

Development

The server uses Node 20 or newer and has no database or hosted component. Request signing follows Portal's current HMAC documentation: GET signatures omit query parameters and content type; the API secret is used as the raw ASCII HMAC key and is not Base64-decoded.

See CHANGELOG.md for release history and BUILD-INFO.md for the release contract.