Management API

The management API lets you do from code what you do in the dashboard: import APIs, publish them, create connections and endpoints, and read logs and usage.

• Base URL: https://pipmcp.com/api/v1
• Format: JSON requests and responses. Successful responses wrap the payload in data.
• OpenAPI description: https://pipmcp.com/api/v1/openapi.json, no authentication needed. Import it into your API client, or into PipMCP itself.
• IDs are the public IDs shown in the dashboard and returned by the API.

Authentication

Create a workspace API token under Settings, API tokens, choose its scopes and copy it: it starts with pmk_ and is shown once. Send it as a bearer token:

curl https://pipmcp.com/api/v1/integrations \
  -H "Authorization: Bearer pmk_your_token"

Tokens act on the workspace they were created in. Writes are attributed to the user who created the token. The scopes are listed in Authentication.

Errors and limits

Status	Body	Meaning
401	{"error": {"code": "UNAUTHENTICATED", ...}}	Missing, invalid, expired or revoked token
403	{"error": {"code": "INSUFFICIENT_SCOPE", ...}}	The token lacks the scope for this route
403	{"error": {"code": "WORKSPACE_INACTIVE", ...}}	The workspace is suspended or scheduled for deletion
402	{"error": {"code": "PLAN_LIMIT", ...}}	The plan's API limit is reached
404		Unknown ID, or it belongs to another workspace
422	{"message": "...", "errors": {"field": ["..."]}}	Validation failed
429		More than 120 requests per minute for this token

Integrations

List integrations

GET /integrations (scope integrations:read)

curl https://pipmcp.com/api/v1/integrations -H "Authorization: Bearer pmk_your_token"

Create an integration

POST /integrations (scope integrations:write) creates the integration and starts its first import.

Field	Type	Notes
source_type	string, required	openapi_url, openapi_upload, postman, graphql, docs_url or manual
name	string	Defaults to the title in the spec
url	string	For URL-based sources. Must be a public http(s) URL
content	string	The definition itself, up to 10 MB
manual	object	Endpoint definitions for manual
wait	boolean	true runs the import before responding

curl -X POST https://pipmcp.com/api/v1/integrations \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"source_type": "openapi_url", "url": "https://api.example.com/openapi.json", "wait": true}'

Get an integration

GET /integrations/{id} (scope integrations:read) returns the integration with its current version, import status and summary.

Re-import

POST /integrations/{id}/imports (scope integrations:write) creates a new version. Send url or content to use a different source; otherwise the stored source URL is fetched again. Returns 202.

curl -X POST https://pipmcp.com/api/v1/integrations/<id>/imports \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{}'

Publish

POST /integrations/{id}/publish (scope integrations:write) publishes the current version. Returns 422 with the reasons if publishing is blocked (unfinished import, mappings that need review, failing tools). See Versioning.

curl -X POST https://pipmcp.com/api/v1/integrations/<id>/publish -H "Authorization: Bearer pmk_your_token"

Tools

List tools

GET /integrations/{id}/tools (scope tools:read)

Update a tool

PATCH /tools/{id} (scope tools:write)

Field	Type	Notes
display_name	string	Up to 120 characters
description	string	15 to 600 characters; instruction-like text is rejected
visibility	string	enabled or disabled
confirmation_policy	string	never, policy or always

curl -X PATCH https://pipmcp.com/api/v1/tools/<id> \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "disabled"}'

Connections

List connections

GET /connections (scope connections:read). Secrets are never returned; secret_keys lists which secret fields are set.

Create a connection

POST /connections (scope connections:write)

Field	Type	Notes
integration_id	string, required
name	string, required
auth_type	string, required	none, api_key_header, api_key_query, bearer, basic, oauth2_authorization_code, oauth2_client_credentials, custom_headers
environment	string	production, sandbox or custom
base_url_override	string	Use a different base URL than the spec's server
settings	object	Non-secret fields, e.g. parameter_name
secrets	object	Write-only secret fields, e.g. api_key, token, username, password, client_id, client_secret

curl -X POST https://pipmcp.com/api/v1/connections \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "<integration id>",
    "name": "Production",
    "auth_type": "api_key_header",
    "settings": {"parameter_name": "X-API-Key"},
    "secrets": {"api_key": "your-upstream-key"}
  }'

The field names per auth type are listed in Authentication. OAuth authorization code connections still need a user to complete the sign-in in the dashboard.

Test a connection

POST /connections/{id}/test (scope connections:write) returns { "ok": true|false, "message": "...", "status": 200, "operation": "GET /..." }.

MCP endpoints

List endpoints

GET /mcp-endpoints (scope endpoints:read)

Create an endpoint

POST /mcp-endpoints (scope endpoints:write)

Field	Type	Notes
name	string, required
slug	string	Lowercase letters, digits and dashes; derived from the name if omitted
policy_preset	string	read_only, safe_writes (default), no_destructive, confirm_external or custom
integrations	array, required	Items of { "integration_id": "...", "connection_id": "..." }
create_token	boolean	Also create an access token and return it once as access_token

curl -X POST https://pipmcp.com/api/v1/mcp-endpoints \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing",
    "policy_preset": "safe_writes",
    "integrations": [{"integration_id": "<integration id>", "connection_id": "<connection id>"}],
    "create_token": true
  }'

The response includes data.url (https://mcp.pipmcp.com/<workspace>/<endpoint>) and, with create_token, the pmcp_ token. Store it: it cannot be retrieved later.

Update an endpoint

PATCH /mcp-endpoints/{id} (scope endpoints:write) accepts name, status (active or disabled), policy_preset and integrations (replaces the list).

curl -X PATCH https://pipmcp.com/api/v1/mcp-endpoints/<id> \
  -H "Authorization: Bearer pmk_your_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'

Executions

List executions

GET /executions (scope executions:read). Query parameters: status (e.g. failed, denied, confirmation_required) and per_page (up to 100, default 50). Returns data plus meta with current_page, last_page and total.

curl "https://pipmcp.com/api/v1/executions?status=failed&per_page=20" -H "Authorization: Bearer pmk_your_token"

Get an execution

GET /executions/{id} (scope executions:read) includes the redacted input, the policy decision, the result summary and each upstream step with redacted request and response.

Usage

GET /usage (scope usage:read)

{
  "data": {
    "period": "2026-09",
    "metric": "agent_actions",
    "used": 1284,
    "limit": 50000,
    "plan": "pro",
    "overage_enabled": true
  }
}