Building an MCP Server for Oracle Primavera P6

Oracle Primavera P6 is the scheduling system of record on many enterprise construction and capital projects. Its REST API is very large and its documentation is uneven, which makes it hard for an AI agent to use well. If you give an agent the raw API, it has to guess which endpoint to call, in what order, with what IDs and filters, and nothing stops it from making a change it shouldn't.

We built P6 MCP to fix that. It is a governed Model Context Protocol server that lets Cursor, Claude Desktop, or any MCP-compatible client discover, plan, and execute P6 operations safely. It also analyzes exported XER files offline, with no live P6 connection. This article covers how it is put together, the decisions behind it, and what carries over to any team wiring agents into a scheduling system.

The problem: P6 is too big to hand an agent raw

The P6 REST API exposes 585 operations across 101 entities. That size is the problem. Many "AI plus enterprise API" integrations take the OpenAPI spec, turn every endpoint into a tool, and hope the model works it out. With P6 that fails in predictable ways:

• Context overload. Hundreds of tool definitions crowd the model's context before it has done any work, and choosing from them gets less reliable as the list grows.
• Hidden dependencies. Many P6 calls only work if you already have the right object IDs from another call. An agent that doesn't know the dependency chain sends bad requests.
• No guardrails. A raw tool list treats reading a project list and changing activity data the same way. In a live schedule that is not acceptable.
• Thin documentation. If the docs don't explain how an entity behaves, the agent can't either.

We took the opposite approach. We generate a structured catalog of what P6 can do, including dependency metadata and risk classes. We wrap every execution in governance. Then we give the agent a small, smart surface (discovery, planning, execution) in place of 585 raw endpoints.

Step one: curate the knowledge before writing tools

The build started with source material, not code. We scraped the full P6 help documentation and API reference and combined it with the official P6 OpenAPI spec. We also pulled in LLM-ready reference text on how to build MCP servers, so the code generation followed the protocol's conventions.

That curated corpus feeds a code generation pipeline:

1. OpenAPI spec plus scraped docs go in.
2. Codegen produces a capability catalog (p6_catalog) and a typed REST client (p6_client).
3. The catalog is generated ahead of time and loaded as a bundle, with search over operations and a dependency graph between them.
4. The client handles authentication adapters, a filter DSL for P6 queries, and session pooling.
5. The gateway runtime sits on top and is the only thing the agent talks to.

The lesson: when an API is this big, generate the integration from the spec and the docs instead of writing it by hand. The catalog is rebuilt from upstream instead of drifting away from it. This is the "built as code" principle from our approach.

How the gateway runtime works

Everything runs through p6_gateway. The agent never calls Oracle directly. The gateway is an orchestration layer that decides how to meet a request and whether it is allowed. The structure looks like this:

MCP client (Cursor / Claude Desktop / custom)
   -> p6_gateway runtime
      -> p6_catalog (generated bundle + search)
      -> p6_client (typed REST + session pool)
      -> workflow playbooks
      -> policy, audit, cache, rate limit, metrics
      -> p6_xer offline tools
   -> Oracle P6 REST + XER files

Inside the gateway there are two layers. The capability layer defines what the server can do. The governance layer defines the rules it must follow while doing it: policies, approvals, auditing, and metrics. A request passes through rate limiting, the response cache, and policy checks before the typed client authenticates and calls the P6 REST API. Every request is recorded so we can see which tools and sequences are used most and turn them into better workflows.

The server runs as a streamable HTTP MCP endpoint, on port 8000 at /mcp by default.

24 gateway tools in place of 585 endpoints

The agent gets 24 purpose-built tools, not one tool per endpoint. They cover:

Ranking and discovery keep context small

Ranking is what makes 585 operations manageable. When a user asks for something, the gateway runs the request against the catalog, workflows, and policies, then searches for the operations that fit, along with the dependencies, required fields, and parameters each needs. The agent sees a short, relevant shortlist, not the full API.

After that, policy decides whether the operation may run in this context and whether it needs approval. A first session typically goes get_session_context, then discover_operations, then list_projects: orient first, find the right operation second, execute third.

Workflow playbooks make sequences repeatable

Many useful P6 tasks take several calls in a specific order. We capture these as workflow playbooks, which are YAML files that list the tools, capabilities, requirements, and parameters for a workflow. When a workflow starts, the gateway:

1. Loads the playbook.
2. Resolves the endpoints and the data each step needs.
3. Runs the tools in the right sequence.
4. Routes any gated step through the approval process.
5. Records checkpoints, failures, and successes.

Playbooks are meant to grow. Each one makes endpoint selection smarter for a specific intent, so the agent stops working out the same sequence from scratch every time.

Offline XER analysis: useful without a live connection

Not every scheduling question should touch a live P6 database. Often the safest first move is to export the project and analyze the file. P6 MCP includes 13 offline XER tools, built on the pyp6xer library, that work directly on an exported XER file:

• Parsing the file and listing activities
• Critical path identification
• Schedule quality checks
• Resource utilization and resource details
• Work breakdown structure (WBS)
• Activity relationships
• Calendars
• Schedule summary
• Earned value and activity detail

The flow is simple: export the project from P6, hand the file to the server, and run the XER tools. Because these tools sit in the same MCP server as the live REST tools, one agent session can be hybrid. It can review the exported baseline offline and then check current state through the API, only where needed.

This follows our default for schedule work: read-oriented inspection first. Offline analysis needs no live credentials and cannot change the schedule.

Multi-tenant by design: orgs, connections, and credentials

A P6 server shared across teams or clients has to keep their access completely separate. A FastAPI control plane manages organizations, connections, profiles, and auth configuration. Onboarding works like this:

1. A new organization is created and adds its grouping.
2. It configures and saves its P6 connection.
3. A starter template connects its MCP client (Cursor or Claude).
4. It starts running reports and workflows.

Credentials are provisioned per organization and partitioned. They are never exposed publicly and never shared across organizations. Identity mapping happens in the backend service, so no two organizations ever use the same authorization tokens. The backend runs on Postgres, with Redis supporting multi-tenant operation.

Observability: know what the agent is doing

Prometheus metrics and audit logs show which tools are called, how often, and whether they succeed. That telemetry serves two purposes. Operationally, it tells you the tools are healthy and flags failures, including when an upstream API change breaks something. For product development, it shows which operations people actually use, which is the evidence for adding a new playbook or improving one. We cover this pattern in more depth in MCP gateway telemetry and the tool runtime.

Running it

The stack is Python 3.12 in a uv workspace, using MCP, FastAPI, httpx, Pydantic, PyYAML, PyJWT, Prometheus, and pyp6xer. For local work there is a Docker Compose sandbox with a mock P6, Postgres, and Redis, so you can test the full flow without touching a real environment. For production there are Kubernetes and Helm deployment assets. Hosting the server remotely behind a streamable HTTP URL keeps credentials server-side and gives everyone a single place to connect.

A test suite runs as the server changes, checking that tools behave as expected, follow the security rules, and keep orchestrating correctly. The project also documents its current status and known limitations, which we think any agent-facing integration should do.

What this means for scheduling and project controls teams

If you own P6 schedules, the takeaway isn't "let an AI edit your schedule." It is a more controlled, more useful way to put an agent next to your schedule data:

• Faster answers from existing data. Critical path, WBS rollups, resource loading, and earned value questions can be answered from an XER export in a conversation, not a manual review.
• Writes stay controlled. Changes to live P6 go through policy, preview, and approval by a designated user. They should be scoped to non-production until you sign off.
• Every action leaves a trail. Audit logs show who asked for what, which operations ran, and what came back.
• Your team's know-how becomes reusable. A playbook for a recurring task captures your process once and runs it the same way each time.

For a broader view of where AI fits in CPM scheduling, see AI for CPM scheduling and Primavera P6.

Practical lessons for wrapping any large enterprise API

1. Curate before you code. Specs, help docs, and protocol guidance together give the generator, and the agent, enough context to act correctly.
2. Generate, don't hand-write. A codegen pipeline from the OpenAPI spec keeps hundreds of operations consistent and easy to regenerate.
3. Expose a small surface. Discovery, planning, and execution tools backed by ranking work better than one tool per endpoint.
4. Model dependencies explicitly. Knowing which calls produce the IDs other calls need prevents most failed requests.
5. Classify risk and gate writes. Reads and writes are different. Preview mutations and require approval where policy says so.
6. Offer an offline path. File-based analysis answers many questions without live credentials.
7. Isolate tenants at the credential layer. Partition per organization from day one.
8. Instrument everything. Telemetry is how the server gets better over time.

These are the same principles behind our governance model and our guide to governing AI agents in construction.

Where to go next

• Watch the full walkthrough and read the transcript: Oracle Primavera P6 MCP Server demo
• New to the protocol? Start with What is MCP for construction
• See how routing works across a much bigger API: Routing 2,755 Procore API tools
• Have a P6 workflow you want an agent to handle, with the right guardrails? Tell us what to build.