Presscart

Presscart MCP

The official Model Context Protocol server for Presscart, a marketplace for disclosed paid editorial placements across 1,700+ publications. It lets AI assistants and agents browse the outlet catalog, manage campaigns and orders, and track article status through the Presscart API.

Hosted endpoint: https://mcp.presscart.com/mcp — see Client Setup for connecting from Claude, Cursor, VS Code, ChatGPT, and other MCP clients. A Presscart account is required.

Supports:

• hosted Streamable HTTP mode

Hosted HTTP mode supports two auth models:

• MCP OAuth mode: Supabase/Auth issues the OAuth token, and clients connect to /mcp with Authorization: Bearer .
• Legacy direct-token mode: the caller provides a Presscart API token via X-Presscart-API-Token, and the server uses that token as the upstream Presscart credential.

Environment

Required:

export PRESSCART_API_URL="http://api.presscart.com/"

Optional app link settings:

export PRESSCART_APP_URL="https://app.presscart.com"

Optional hosted mode settings:

export MCP_HOST="0.0.0.0"

export MCP_PORT="8787" export MCP_SERVER_URL="https://mcp.presscart.com/mcp" export MCP_SESSION_IDLE_TTL_MS="43200000"

Optional host/origin overrides for reverse proxies or multiple domains:

export MCP_ALLOWED_HOSTS="mcp.presscart.com"

export MCP_ALLOWED_ORIGINS="https://mcp.presscart.com,https://claude.ai,https://claude.com"

When MCP_ALLOWED_ORIGINS is not set, hosted mode allows the configured MCP server origin plus Claude's remote connector origins.

Optional OAuth settings:

export MCP_OAUTH_ENABLED="true"

export MCP_OAUTH_ISSUER_URL="https:// .supabase.co/auth/v1" export MCP_OAUTH_AUDIENCE="https://mcp.presscart.com/mcp" export MCP_OAUTH_TRANSLATOR_ENABLED="false" export MCP_OAUTH_LEGACY_AUDIENCE="https://mcp.presscart.com" export MCP_OAUTH_UPSTREAM_TIMEOUT_MS="10000"

Optional directory integration settings:

export MCP_DIRECTORY_PROFILES="openai,claude-directory"

Optional OpenAI plugin domain verification:

export OPENAI_APPS_CHALLENGE_TOKEN="<challenge_token_from_openai_portal>"

Notes:

• PRESSCART_API_URL must point at the app API base that exposes /teams/* routes, not a public-api-only base.
• PRESSCART_APP_URL controls direct application links returned by tools such as list_publisher_articles. Set it per environment so staging MCP links open staging.
• Tools that create orders/campaigns or read profile orders need an explicit profile_id. If the profile is unknown, call list_teams, then list_profiles.
• In MCP OAuth mode, the app's Supabase OAuth Server handles authorization and consent. This MCP runtime validates the issued access token against Supabase JWKS and delegated permissions.
• MCP_OAUTH_TRANSLATOR_ENABLED defaults to false. When enabled, the MCP origin publishes a standards-based OAuth facade while Supabase remains responsible for clients, codes, tokens, rotation, signing, and consent.
• MCP_OAUTH_ISSUER_URL must use HTTPS. Loopback HTTP issuers are accepted only for local development.
• MCP_OAUTH_LEGACY_AUDIENCE is an optional verifier-only migration value and must equal the configured MCP server origin (for example, https://mcp.presscart.com). It cannot duplicate the canonical /mcp resource or name another service, and it never changes the protected resource advertised to clients.
• MCP clients store their own refresh tokens, initiate refresh automatically, and replace rotated refresh and access tokens. This server handles the refresh request statelessly and does not store refresh tokens.
• The translator changes only MCP OAuth. It does not change ordinary Presscart browser or app sessions, and disabling MCP OAuth still preserves legacy direct-token mode.
• In legacy direct-token mode, send X-Presscart-API-Token: on initialize and later requests that need to confirm the active session credential.
• OPENAI_APPS_CHALLENGE_TOKEN is the domain-verification token shown in OpenAI's plugin portal. When set, GET /.well-known/openai-apps-challenge returns it as text/plain with no authentication, on the MCP hostname's origin (the portal ignores the /mcp/openai path). Surrounding whitespace is trimmed; when unset or blank, the route returns 404. If MCP_ALLOWED_HOSTS is set, it must include the public MCP hostname.

Install

cd presscart-mcp

npm install

Run

Development:

npm run dev:http

Build and run:

npm run build

npm start

Build and run hosted HTTP:

npm run build

npm run start:http

Release

Releases are automated by semantic-release from Conventional Commits.

• fix: creates a patch release.
• feat: creates a minor release.
• ! or BREAKING CHANGE: creates a major release.
• docs:, test:, chore:, and other non-release commits do not publish a new version by default.

The Release workflow runs on pushes to main and staging. It runs check, test, and build, then semantic-release creates the release tag and publishes the GitHub release.

• main publishes stable releases and commits generated release files: CHANGELOG.md, package.json, package-lock.json, and src/version.ts.
• staging publishes release candidates with the rc prerelease channel, but does not commit generated release files. This keeps staging-to-main promotion merges from conflicting on prerelease metadata.

You can dry-run the release locally:

npm run release:dry-run

npm run release:staging:dry-run

If the repository has no existing release tag yet, create the baseline tag before the first semantic-release run so the next release continues from the current version:

git tag v0.2.0

git push origin v0.2.0

Tools

• get_user
• list_teams
• get_team
• list_profiles
• upload_files
• list_outlets
• get_outlet
• create_outlet
• update_outlet
• get_outlet_statistics
• start_outlet_domain_verification
• verify_outlet_domain
• get_outlet_authorization
• submit_outlet_authorization
• list_outlet_channels
• create_outlet_channel
• update_outlet_channel
• delete_outlet_channel
• list_product_types
• list_product_listings
• list_countries
• list_states
• list_cities
• get_product_listing
• list_products
• get_product
• create_product
• update_product
• set_product_active
• create_order
• get_order
• list_order_items
• list_profile_orders
• create_campaign
• list_campaigns
• get_campaign
• update_campaign
• list_campaign_articles
• list_publisher_articles
• add_order_items_to_campaign
• get_campaign_article_status
• upload_campaign_questionnaire
• upload_article
• replace_article_file
• submit_article
• request_article_writing
• get_publisher_agreement_status

Directory routes

/mcp keeps the full tool set. The OpenAI and Claude directory integrations connect to separate URLs whose tool exposure is fixed by server configuration:

• A route is mounted only when its id is listed in MCP_DIRECTORY_PROFILES (comma-separated, default empty). An unknown or duplicate id stops startup. Unlisted profile paths return 404.
• Both profiles expose the same ten read-only tools: get_user, list_teams, get_team, list_profiles, list_profile_orders, get_order, list_campaigns, get_campaign, list_campaign_articles, get_campaign_article_status. Every other tool is not registered on these routes, so calling it fails before any Presscart API request.
• Directory tools return explicit field allowlists (no prices, payment or checkout fields, emails, writer names, internal document links, or add-ons), advertise strict output schemas, and cap limit at 25.
• A session belongs to the route it was initialized on. Sending its Mcp-Session-Id to any other MCP route returns 404 Session not found.
• Exposure is not authorization: the Presscart API still authorizes every request.
• With MCP_OAUTH_ENABLED=true, each directory route has its own protected-resource metadata and WWW-Authenticate challenge, the OAuth facade accepts its resource on /oauth/authorize and /oauth/token, and its verifier accepts only that route's resource as the token audience. A token whose audience is the canonical /mcp resource (or the legacy origin) is refused there, and a directory token is refused by /mcp.
• With MCP_OAUTH_ENABLED=false, directory routes use X-Presscart-API-Token like /mcp. Use this only for local and staging testing.
• Rollback: remove the profile from MCP_DIRECTORY_PROFILES and redeploy. /mcp is unaffected.

Before submitting to a directory:

1. Verify in staging that Supabase OAuth accepts the forwarded directory resource value.
2. The Presscart API gives tokens from a directory sign-in that route's audience (presscart-app #910). Confirm this on staging before submission.

Hosted deployment shape

MCP OAuth mode

Enable OAuth:

PRESSCART_API_URL=http://api.presscart.com/

MCP_HOST=0.0.0.0 MCP_PORT=8787 MCP_SERVER_URL=https://mcp.presscart.com/mcp MCP_SESSION_IDLE_TTL_MS=43200000 MCP_OAUTH_ENABLED=true MCP_OAUTH_ISSUER_URL=https:// .supabase.co/auth/v1 MCP_OAUTH_AUDIENCE=https://mcp.presscart.com/mcp MCP_OAUTH_TRANSLATOR_ENABLED=false MCP_OAUTH_LEGACY_AUDIENCE=https://mcp.presscart.com MCP_OAUTH_UPSTREAM_TIMEOUT_MS=10000

The canonical resource and JWT audience must match MCP_SERVER_URL, allowing only a trailing-slash difference. Both public OAuth URLs and the upstream issuer must use HTTPS except for loopback-only local development. MCP_OAUTH_LEGACY_AUDIENCE is needed only during the migration window, must match the MCP server origin exactly, and should otherwise be unset.

With the translator disabled, the server exposes direct-Supabase protected-resource metadata (advertising only the profile scope, because Presscart's access token hook refuses any code exchange that asks for openid) at:

• /.well-known/oauth-protected-resource
• /.well-known/oauth-protected-resource/mcp

With the translator enabled, those routes advertise https://mcp.presscart.com as the authorization server, and the server also exposes:

• /.well-known/oauth-authorization-server
• /oauth/authorize
• /oauth/register
• /oauth/token

The facade accepts the standard authorization-code and refresh-token flows and proxies only to the configured Supabase issuer. It does not derive upstream targets from request hosts, forwarded headers, query parameters, or client-supplied URLs.

The facade does not expose or advertise an RFC token-revocation endpoint. Revocation stays in the existing Presscart app/admin flow: revoking the Presscart OAuth grant makes the next refresh fail. An access token that was already issued is not actively revoked by this MCP verifier and can remain cryptographically valid until its normal expiry. After it expires, the client cannot obtain a replacement, access ends, and the user must reauthorize.

Hosted MCP clients should connect to https://mcp.presscart.com/mcp and use normal MCP OAuth discovery. After the browser flow completes, they send Authorization: Bearer to /mcp. Clients own refresh-token storage, automatically initiate refresh, and persist each rotated refresh token returned by Supabase through the facade.

ChatGPT, Claude, Cursor, and Codex consume the same MCP and OAuth standards. The server has no vendor-specific authentication branches. Labels and prompts such as Connect or Authenticate are controlle