ProWorkflow MCP Server

Model Context Protocol server exposing ProWorkflow resources as tools for AI assistants.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. This server exposes ProWorkflow's core resources — companies, contacts, projects, items, phases, invoices, quotes, time entries, time allocations, and messages — as callable tools.

Resources

• Companies — Client, contractor, staff organizations
• Contacts — People associated with companies
• Projects — Project records with team assignments and scheduling
• Items — Project tasks with assignments, dates, and financials
• Phases — Project phase hierarchy and rollup records
• Invoices — Invoice records with payment tracking
• Quotes — Quote/estimate records with approval status
• Time — Time tracking entries against project items
• Time Allocations — Planned/allocated time linked to items and contacts
• Messages — Project messages and communication
• Custom Fields — Project custom field definitions and dropdown options

Operations

• LIST Search and filter with pagination
• GET Retrieve a single record by ID
• CREATE Create a new record
• UPDATE Update an existing record
• DELETE Soft-delete a record

POST /api/v4/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "status": "active",
      "pagesize": 10
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"status\":\"success\",\"data\":[...]}"
    }]
  }
}

Authentication

All MCP requests require authentication via one of two methods:

API Key

Pass your ProWorkflow API key in the apikey header.

Bearer Token (JWT)

Pass a JWT token in the Authorization header.

curl -X POST '/api/v4/mcp' \
  -H 'Content-Type: application/json' \
  -H 'apikey: xxxx-xxxx-xxxx-xxxx-PWFxxxx' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

curl -X POST '/api/v4/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbG...' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

How It Works

The MCP server uses JSON-RPC 2.0 over Streamable HTTP. All communication happens via POST /api/v4/mcp.

Step 1: Initialize

Send an initialize request to establish the session. The server responds with its capabilities and protocol version.

Step 2: List Tools

Send tools/list to discover all available tools and their input schemas. Each tool has a name, description, and JSON Schema for its parameters.

Step 3: Call Tools

Send tools/call with the tool name and arguments. The server executes the operation against the ProWorkflow REST API and returns the result.

Session Headers

After initialization, the server returns an mcp-session-id header. Include this header in subsequent requests to maintain the session.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_company",
    "arguments": {
      "id": 42
    }
  }
}

Errors

Tool errors are returned inside the CallToolResult with isError: true. The error message is in the content array as a text block.

Common Error Scenarios

Scenario	Error Message
Missing required parameter	id is required and must be > 0
Invalid credentials	API error (HTTP 401): ...
Permission denied	API error (HTTP 403): ...
Record not found	API error (HTTP 404): ...
Validation error	API error (HTTP 400): ...
Rate limited	API error (HTTP 429): ...

JSON-RPC Errors

Protocol-level errors (invalid JSON-RPC, unknown method) return standard JSON-RPC error responses with negative error codes.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{
      "type": "text",
      "text": "API error (HTTP 403): {\"status\":\"error\",\"data\":[\"Permission denied\"]}"
    }],
    "isError": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}