Procore MCP Architecture

[00:00] All right, today we are reviewing the Procore MCP that I created. It is quite extensive and very capable. There's a lot implemented, more than most MCP servers, and there's a lot more that can be continued and developed on top of this. This Procore MCP server specifically is very extensive, and it contains every single API endpoint as a tool. There are different functionalities and capabilities with regard to workflows, personas and policies implemented in here, along with all of the different API requests that can be leveraged within Procore. Essentially, Procore has many different API endpoints, and they span

[00:45] across many different solutions and capabilities embedded within Procore. When you're creating an MCP server, essentially what happens is this context is provided to the agent every single time the large language model is called. Because that's happening, if we were to provide all of the context for how these tools are defined, what capabilities there are, and how to make those API requests, it would be too much context overload for the large language model to ingest as input tokens. So there are ways to get around this and implement solutions that counteract this context overload, and we can then implement various types of capabilities within the MCP server. So

[01:30] when the agent is utilizing the tools, we created basically a subsection of tools that is able to search through the API endpoints and leverage the embedding models we've implemented, which reference the API documentation along with all of the different tools, policies, capabilities and workflows that are created. The whole idea is that this MCP server has the ability to use a subset of tools that we have created to search, identify and understand what tools to use and when to use them.

[02:15] So the first thing is, when you run this, you can actually run it where all 2,755 tools are exposed. If you have a client that has the ability to select specific tools to be used for the agent, where it only provides that context, you can run that. But there's also a way to run this MCP server with meta-tools, as described here, where these tools give the agent the capability to understand the user's context and their intentions, and then take that and identify what tools are needed and in what order and sequence. We support that by creating different capability YAML files. We create workflows, personas and

[03:00] different policies. Then we leverage hybrid search to search through the vectorized embeddings that we created, and we run a ranking protocol to identify, "Here are the tools, based on the user's intent, that the agent will need access to." We provide that back to the agent and ultimately make those requests in a specific order, normalizing that data. The server also includes many different safety checks, observability and self-tuning, so we can consistently learn and develop, and there's also the ability to inject plugins and evaluation benchmarks to ensure that it's functioning properly. The whole concept, though, is that we

[03:45] have a large language model client. This could be something like Claude or Cursor. Then we have the MCP transport layer that is reading those tools. This transport layer leverages a streamable HTTP MCP, which is the Procore MCP created here, and then it selects the mode that we're leveraging. That mode is either the expanded one that provides all the different tools, or it could be the subsection of tools, like the meta-tools that we created, which will identify the user's intent and dispatch it to the subsection of routing where it ultimately needs to go, whether that's through the jobs that are implemented

[04:30] for running this for multiple different users on multiple different clients, and/or multiple different Procore instances as well. It also sends it through telemetry and auditing, capturing all the metrics as well. And then ultimately we have the tool call layer. To dive further into some of this, there are two transports. Streamable HTTP is the main one, for hosting this on a remote server. It's hosted through a Dockerized container that can be deployed anywhere. It can also be hosted locally if necessary. But streamable HTTP is the best, where we're passing authentication headers and we're able to leverage it for multiple different users at the same time.

[05:15] Within layer two, the mode selection, like we said, there's the expanded mode that just provides all tools. There's also hybrid. That one has some tools based on the policies we provide, or on headers we provide in the request, that define a specific persona or focus area of the organization and what they're trying to accomplish, like RFIs. Then it only pulls those specific tools in. And then there's the router, which is the intelligent router that identifies the user's intent and routes it to the correct tooling for that use case. When we utilize this tooling, it goes through and identifies all

[06:00] of the semantic embeddings, ranks them, and is able to reference specific tools and capabilities based on the user's intent through natural language, searching through the tools, capabilities, workflows and policies that are implemented, which then dives further into how those are being dispatched. Then we have a multi-tenant infrastructure that normalizes data. There are pre-flight checks. There's IP registration, rate limiting and policy execution to make sure these users are abiding by the capabilities the MCP is allowed to provide. Whether you want to restrict delete actions, or have

[06:45] checksums for when someone's trying to create something, you want a validation loop for that. There are also many other capabilities in terms of GDPR compliance, as well as data redaction and various plugins that can be implemented. Then there are different clients that can be leveraging this type of solution. When we're pulling in this information, what we're doing is saying, "Here are all of the tools that are able to be run." This is generated from the combined OpenAPI specs that Procore has. And so through running that through our

[07:30] solution, it's able to implement all of the features, definitions, handlers and registration for all of these different tools and capabilities. Essentially there's a program that runs through all the OpenAPI specs and puts in all the definitions and capabilities. Then we have our orchestration layer that determines when and how to use those. This runs on Node.js with TypeScript, and clients will need their client ID and client secret along with their company ID. We can install this on any remote server and have it run. We have to set our environment variables on the back end to make it function. Then we run it as a streamable HTTP

[08:15] MCP server and have it hosted at the URL of our choice. Here's the basic structure for how we would make these requests to the MCP server. There are the authentication headers and how we're streaming the events, as well as different types of tools and capabilities. As you can see down here, we can set specific parameters. If there are capabilities we want to implement on the back end to define how this is supposed to function, that's where the workflows, policies, personas and everything come into play. Here are some more examples of how they can be referenced in terms

[09:00] of creating personas, routing to specific things, redacting specific data and/or implementing specific capabilities. And of course, we talked about the expanded, hybrid and router functionality. We define this within the authentication headers of the MCP request. There are a bunch of different tools implemented as the meta-tools, and these are basically segmented into discovery and description, so the agent knows how to search for tools, describe these tools, gather the context and understand what's being implemented, and then the calling of these tools. So how does it make these requests? How is it paginating and

[09:45] chunking the different calls and making those calls in sequence? We have resolution, to ask specific questions if the agent needs more context or information from the user, as well as multi-step intelligence. This is important for identifying the functionality users are most likely to need, which tools need to run, in what order, and what data needs to be supplied to make those requests. That's where the true intelligence layer is. And then ultimately the routing. As this routes to different tools and capabilities, there's a feedback loop

[10:30] implemented so it can continuously learn, develop and improve as it's being tested and used. And of course we run these through async jobs. If there are specific jobs being run, or we need a backend service to run while things happen on the back end, we've implemented different capabilities for that. Then there's caching and state, to identify data that is session-persistent or organization-persistent, which can continuously learn and evolve through adoption of this solution. Diving further into capabilities, workflows, personas and policies: these of course can be expanded and developed. They are all

[11:15] vectorized, so they're easily searchable and identifiable. There are different capabilities within the tools that need to be implemented. For someone working with RFIs, there may be multiple different tools needed, as well as policy restrictions and rules for how we implement those capabilities within the agent, as well as workflows. These workflows are a multi-step sequence of tooling, along with the different types of data needed to make those tool calls and that specific request. Like I said, any of these can be expanded. Of course, there are different personas using this MCP server, and so defining who

[12:00] those personas are lets those specific users have more intentional capabilities and usage toward specific functionality within Procore, so they're more defined in terms of their capabilities and how they would be leveraging the MCP server. And then ultimately, policies. These are very important. There are checksum and validation loops we go through to ensure that specific actions are and aren't happening, whether it's reading information or being able to create or update things, whether it's being used in a sandbox environment, rate limiting, quotas. There are a lot of things

[12:45] that can be implemented to govern the usability of these tools, who's using them, and what they should or shouldn't be able to do with certain aspects of this MCP server. And ultimately this is multi-tenant. These headers can be implemented at the MCP level when making requests. Basically, this MCP server can be used by multiple different teams and multiple different organizations, each segmenting and partitioning their specific instance to ensure that nothing is crossed over and no data crosses between different solutions, teams or organizations. These headers are our ability to

[13:30] partition that specific instance and then route it to the respective area. These are the code generation pipelines. As the API endpoints are developed, enhanced and changed, whether that's new capabilities, different data objects, changes in the URL or whatever it may be, the solution will go through and regenerate all of the tooling: read the API documentation and update the tools within the MCP server. So it's a constant iteration that stays in line with the API's development. The MCP server directly maps the tooling to what the API

[14:15] requires to make the proper requests. Then we run validation workflows to ensure the tools are functioning properly and working correctly. Here are some examples of how we could route requests, how specific functionality makes those requests, and how to reference the data within it. There are some deeper things with regard to policy mechanics: how we abide by certain security privileges and capabilities to ensure that we're in compliance with different organizations' requirements, whether that's HIPAA, SOC 2, GDPR or FINRA as well.

[15:00] This is all to ensure that it's enterprise-level, that organizations know they're safe, their data is safe, and that this tool and the agent we implement can and will abide by the standards their organization requires. Ultimately, all of this runs as async jobs. As multiple teams and users are leveraging this solution, the server is going to be working in overdrive. So there are backend services that need to be running to ensure no user or organization is restricted by another user of the system in terms of

[15:45] response time and latency. This all works on the back end to ensure capabilities are constantly available for each user, allowing them to use the tool to its fullest. Another thing that is very important is observability and telemetry. How is this MCP server functioning? Is it up and running? Is there any downtime, and what metrics are being captured to identify what's occurring within the platform? That could be usage, how frequently tools are being called, if a tool is failing and why it's failing, which organizations or IP addresses are using the tools, and ultimately

[16:30] an overarching understanding of how the MCP server is being used, and the ability to get granular into when it's being called and how it's being called, to gain more insight into where it can be further enhanced or developed, or to inform pricing and availability. There are also different plugins that can be implemented. These could register different workflows, personas, or capabilities for how to resolve certain areas before dispatching and making the actual requests. This is very important for setting policies and rules to ensure that the entire MCP server is working

[17:15] appropriately within the guidelines of the organization using the MCP, or, in Procore's case, the specific requirements their APIs or their organization require. So basically, rule sets that ensure everything functions properly, implemented through these plugins. And then there's evaluation and tuning. This will constantly evolve, develop and learn. As the tools are being used, requests are being made and agents are using this tooling, it's going to learn, evolve and develop, whether through updating specific evaluation frameworks

[18:00] or identifying certain queries that are occurring. This is very important to ensure it keeps being developed and enhanced, and to identify areas that may be important for capabilities to be developed further. For deployment, we're using Docker. I know there are other ways to deploy MCP servers, like Kubernetes clusters, or just running a service on an on-prem server behind a reverse proxy. This is just a very quick and easy way to implement the server as a containerized instance that can be expanded and developed further. And then there are some

[18:45] endpoints being leveraged: as we discussed, the MCP endpoint that streams all the requests and makes the requests, and then the health and metrics endpoints to see how everything's functioning on the back end. And we run it as a multi-tenant workflow. Then we have our project structure here. So what does this MCP ultimately look like? We have our source folder. The source pulls everything in through our index, and the index runs everything through our server, registering all of our tools and setup. We have our client that manages authentication, our tools that hold all our definitions and how they're supposed to be handled, and

[19:30] then our types and where we're routing all this information to. This would be our dispatcher, our workflows, our embeddings: how are we referencing all of this data, looking up data, normalizing data, our policies, planning and all the different jobs? This is really where the core value of the MCP server is. Most organizations just do a one-to-one: this tool is just an API endpoint, and whenever we return this tool to the agent, it makes that request. That's an initial, maybe naive, way of implementing it. It's very early in the ways of leveraging these tools. But where these MCP servers and agents really

[20:15] become intelligent is when we have this entire orchestration of capabilities, to ensure it's enterprise-level, that it has the full capabilities of all these different tools, and that it's able to look up and know exactly what is supposed to be used and when. There's a ton of different capabilities in terms of dashboards, data, all of our routing, capabilities and workflows, as well as the scripts we run to adjust, test and try different things. So it's very robust in terms of its capability. Many of the solutions and ideas implemented here are very new, and most organizations and teams have not necessarily thought about or

[21:00] implemented any of these. These are requirements that will ultimately need to be implemented in an enterprise-level solution with an abundance of API endpoints and tools. There's of course some documentation and resources on how we develop it. Let me know if there are any questions or anything that's needed. Happy to support and assist as necessary. Thank you very much, and I appreciate the time.