portal-api
This read-only MCP server provides access to Portal.io account data through a set of tools, allowing you to test credentials, browse proposals, search contacts, list users, and search the catalog (if enabled). All operations are strictly read-only; no creating, updating, archiving, or sending data is possible.
test_connection: Verify Portal.io API credentials are valid.
list_proposals: List/search proposals with filters (status, contact, text, date modified) and pagination.
get_proposal: Get complete proposal details by ID.
list_users: List active users, useful for finding salesperson IDs.
search_contacts: Search contacts by name, company, email, phone, or contact type (Person/Company), with sorting and pagination.
search_catalog: Search the product catalog by brand, category, text, or stock status; requires Catalog API access to be enabled.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@portal-api list my recent proposals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_proposalsandget_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.1 contains no mutation tools. It cannot create, update, archive, or send anything in Portal.
Related MCP server: readonly-mcp-server
Install
git clone https://github.com/AWfusion/portal-api-mcp.git
cd portal-api-mcp
npm ci
cp .env.example .envFill 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=falseFor 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 .envVerify
npm test
npm run verifynpm 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.shIt registers this local process globally under the name portal-api. Confirm it with:
codex mcp get portal-apiRestart 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 athttps://sandbox.api.portal.io; production credentials belong athttps://api.portal.io.request signature (hash) is invalid: first confirmPORTAL_USER_API_KEYis the Base64meta.apiKeyreturned 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 API contract: GET signatures include the fully encoded request URL and omit the 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.
Available Tools
6 toolsget_proposalA
Get complete details for one Portal.io proposal. Read-only.
Inputs: proposal_id (required).
list_proposalsB
List or search Portal.io proposals. Read-only.
Inputs: sort_by, statuses, page_size, contact_id, +5 more.
list_usersA
List active users in the Portal.io account. Use this to find salesperson IDs. Read-only.
Inputs: no named parameters.
search_catalogB
Search the Portal.io catalog. Catalog API access must be enabled for the account. Read-only.
Inputs: brand, in_stock, page_size, category_id, +2 more.
search_contactsB
Search or list Portal.io contacts. Read-only.
Inputs: sort_by, page_size, page_number, search_text, +2 more.
test_connectionA
Confirm that the configured Portal.io API credentials work. This is read-only and returns only proposal metadata.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct resource and action: proposals (get/list), users (list), catalog (search), contacts (search), and connection test. No overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_proposal, list_users, search_catalog).
6 tools is appropriate for a read-only API surface covering proposals, users, catalog, contacts, and connection verification.
Covers the main read operations for key entities, but lacks get_user or get_contact individually; however, this is reasonable for the scope.
Maintenance
Related MCP Connectors
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Read-only MCP server: verify credentials and browse escrows on the Stellar testnet contract.
Related MCP Servers
- AlicenseAqualityBmaintenanceRead-only MCP server for the RareCloud API, enabling AI agents to list servers, browse the catalog, check billing, and plan deployments.10068 npmMIT
- FlicenseNot gradedqualityDmaintenanceA read-only MCP server with configurable transport (stdio or HTTP+SSE), API key authentication, and scope-based authorization for read and search operations on documents.-
- AlicenseAqualityDmaintenancePortable, read-only MCP server for Nous Portal capabilities, providing configuration status, route derivation, and OAuth device code authentication without invoking paid tools.4MIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that provides tools to list and read devices, MDM servers, blueprints, configurations, apps, packages, users, and other resources from Apple Business Manager and Apple School Manager.MIT