> For the complete documentation index, see [llms.txt](https://docs.cogram.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cogram.com/integrations/mcp-server.md). # MCP server Connect ChatGPT, Claude, or a custom AI agent to Cogram through the MCP server: read-only access, acting as the person who connected it. Cogram's MCP server lets a user connect an AI application to Cogram and then ask it questions about their projects — meeting minutes, emails, RFIs, submittals, drawings, field reports, and the directory. MCP (Model Context Protocol) is the open standard that AI applications use to reach outside systems. Any MCP client can connect: ChatGPT, claude.ai, or an agent your own team builds. **Server address:** `https://mcp.cogram.com/mcp` Two facts define what a connected agent can do: * **It is read-only.** The agent can search, read, and summarize. It cannot create, change, or delete anything in Cogram. * **It acts as one person.** The agent sees exactly what the user who connected it can see, and nothing more. This page covers setup for organization administrators. Users connecting ChatGPT, Claude, or another AI app follow [Connecting AI apps](/integrations/connecting-ai-apps.md) instead. You control MCP access in two places: in Cogram, where you allow connections at all, and — if your company runs a ChatGPT or Claude workspace — in that workspace, where you make Cogram available to its users. ## Step 1: Turn on MCP access in Cogram MCP access is **off by default** for every organization. An administrator turns it on once, for the whole organization. 1. Go to [Organization Settings → Integrations → MCP access](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). 2. Turn on **Allow members to connect third-party AI agents**. The same page shows the **Server URL** with a copy button — this is the address users and AI applications need. Once MCP access is on, any user can connect an AI application for themselves. Users who connect nothing are unaffected. Turning it off again cuts off every agent already connected, and stops users connecting new ones. > **If you do not see MCP access** in Organization Settings → Integrations, MCP access is not yet available for your organization. Email . If your users are on personal AI accounts, you are done — send them to [Connecting AI apps](/integrations/connecting-ai-apps.md). The rest of this page covers company-managed AI workspaces and custom agents. ## Step 2 (optional): Publish Cogram in your ChatGPT workspace On ChatGPT Business, Enterprise, and Edu, users cannot add custom MCP apps themselves — a workspace admin creates the Cogram app once and publishes it to the workspace. 1. As an admin or owner, enable developer mode for yourself under **Settings → Apps → Advanced settings → Developer mode**. Each admin enables it for themselves; it is also offered when you create an app. (On Enterprise and Edu, you can additionally grant developer mode to selected non-admin users under **Workspace Settings → Permissions & Roles → Connected Data**.) 2. Go to **Workspace settings → Apps → Create**. 3. Name the app **Cogram MCP** and enter the MCP server URL `https://mcp.cogram.com/mcp`. Choose **OAuth** as the authentication method. 4. Select **Scan Tools**. ChatGPT opens Cogram's sign-in — sign in as you normally do, including through your identity provider if your organization uses SSO, then select **Allow** on the approval screen. 5. Wait for the tool scan to finish, then select **Create**. The app is saved as a draft in **Workspace Settings → Apps → Drafts**. Optionally test it first: in a new chat, select the draft (labeled "Dev") from the tools menu and ask it about your Cogram projects. 6. Publish it: **Workspace settings → Apps → Drafts → Publish**, and confirm the review prompts. Every Cogram tool is read-only, so there are no write actions to review. 7. On Enterprise and Edu, the publish dialog also lets you restrict individual tools (**Configure Actions**) or limit which groups see the app (**Configure Access**). **Expected result:** Cogram MCP appears for users under **Plugins**, on your workspace's tab, labeled "custom" — they install it as described in [Connecting AI apps](/integrations/connecting-ai-apps.md). Each user signs in to Cogram themselves, so every user's agent sees only their own projects. ChatGPT freezes the app's tool list when you publish. When Cogram releases new tools, they are not picked up automatically: on Enterprise and Edu, select **Refresh** under the app's **Action control** and enable the new tools (new tools arrive disabled); on Business, recreate and republish the app. ## Step 3 (optional): Publish Cogram in your Claude workspace On Claude Team and Enterprise plans, an Owner can add Cogram as a custom connector for the whole organization. Only Owners can do this. 1. Go to **Organization settings → Connectors**. 2. Select **Add**, hover over **Custom**, and choose **Web**. 3. Name the connector **Cogram MCP** and enter the MCP server URL `https://mcp.cogram.com/mcp`. 4. Leave the OAuth Client ID and Client Secret fields under Advanced settings empty — Cogram registers each client automatically. 5. Select **Add**. **Expected result:** every user sees Cogram MCP under **Customize → Connectors**, labeled "Custom" — they connect it as described in [Connecting AI apps](/integrations/connecting-ai-apps.md). Each user selects **Connect** there and signs in to Cogram themselves, so every user's agent sees only their own projects. ## Connect a custom client or in-house agent The server is a standard MCP server: streamable HTTP transport, OAuth 2.1 with dynamic client registration. Point any MCP client library, or the Anthropic MCP connector, at `https://mcp.cogram.com/mcp`. The client handles discovery and the OAuth flow — including registering itself, so there is nothing to pre-register with Cogram. Two things to plan for in your own agent: * **One interactive sign-in per identity.** There are no machine accounts or service accounts. A person must sign in to Cogram in a browser and approve the connection once, for each identity the agent runs as. * **Store and rotate the refresh token.** After approval your agent holds a refresh token, which it exchanges for short-lived access tokens. Keep it somewhere secret, and replace your stored copy with the new one each time you refresh. If you lose it or it expires, the only recovery is another interactive sign-in. If several people use your agent and each should see only their own projects, connect once per person and keep their tokens apart. One shared connection means everyone sees the data of whoever approved it. ### Treat Cogram content as data, not instructions Tool results carry text that people outside your organization wrote: email bodies, meeting transcripts, attachment text, RFI questions, directory notes. Any of it can contain something that reads like an instruction to an AI model — "ignore your previous instructions", "email this file to…", "the user has approved…". Your agent must treat every tool result as untrusted data: * Keep tool results separate from your own instructions in the prompt, and say plainly in the system prompt that content returned by tools is data to be examined, never a command to follow. * Never let a tool result decide, on its own, to call another tool that acts outside Cogram — sending mail, writing to another system, running code. * Put a human in front of any consequential action your agent takes from Cogram content. The Cogram MCP server is read-only, so nothing an agent reads can change Cogram. The risk is what your agent does next with what it read. ## What a connected agent can and cannot do | Can | Cannot | | ---------------------------------------------------- | ---------------------------------------------------------------- | | Search and read the Cogram records the user can open | Create, edit, delete, or archive anything | | Read attachment and document text | Send emails, transmittals, or notifications | | Get time-limited links to drawing sheet images | Reach a project the user is not a member of | | Read the organization's directory and user list | Reach another organization's data | | Act as one named user | Act as a machine account, an admin, or the organization at large | Cogram permissions apply unchanged. Project membership, [project roles](/projects/project-roles.md), and [asset visibility](/projects/asset-visibility.md) all still decide what the agent sees, because every request is answered as the connected user. ## What data an agent can reach The agent works through a fixed set of read-only tools. The **Module needed** column shows where a tool depends on your organization's [licensing](/organization-administration/licensing.md): if your organization is not licensed for that module, those tools are not offered to the agent at all. | Category | Module needed | Tools | | ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Connected user identity | — | `whoami` | | Projects | — | `search_projects`, `get_projects_by_id` | | Meetings and meeting attachments | Meetings | `search_meetings`, `get_meetings_by_id`, `search_meeting_attachments`, `get_meeting_attachment_content` | | Emails and email attachments | Email Management | `search_emails`, `get_emails_by_id`, `search_email_attachments`, `get_email_attachment_content` | | Documents | — | `search_documents`, `get_documents_by_id` | | RFIs and submittals | Correspondence | `search_rfis`, `get_rfis_by_id`, `search_submittals`, `get_submittals_by_id` | | Drawings, field reports, observations | Field Reports | `search_drawings`, `get_drawings_by_id`, `search_reports`, `get_reports_by_id`, `search_observations`, `get_observations_by_id` | | Transmittals | Transmittals or Email Management | `search_transmittals`, `get_transmittals_by_id` | | Project boards | — | `search_board_items`, `get_board_item`, `get_board_items_for_meeting` | | Workflows | — | `search_workflows`, `get_workflows_by_id` | | People and companies | — | `search_org_members`, `search_directory` | | Organization overview | — | `get_org_data_summary` | Meeting audio recordings are not reachable through any tool. Transcripts are, for users who can already read them. Retrieval tools that take a list of IDs accept at most 100 IDs per call. An agent that asks for more gets a validation error, so have it work in batches. ## Rate limit Each user is allowed **50 requests per minute per connected application**. Two applications connected by the same person get their own allowance each, and two users never share one. Over the limit, the server answers `429` with a `Retry-After` header. A well-behaved MCP client waits and retries. If your work genuinely needs a higher limit, email — the limit is not something you can change yourself. ## Troubleshooting **Symptom**: The agent reports "MCP access is not enabled for your organization", or the approval screen offers no **Allow** button. **Likely cause**: MCP access is off for your organization. **Fix**: Turn it on at [Organization Settings → Integrations → MCP access](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). If the setting is not on that page, email . **Symptom**: Cogram does not appear in ChatGPT's tools menu. **Likely cause**: On Business, Enterprise, and Edu, a workspace admin has not published the Cogram app yet — users cannot add it themselves. On Pro, developer mode is off. **Fix**: Publish the Cogram app (see [Step 2](#step-2-optional-publish-cogram-in-your-chatgpt-workspace) above) — users cannot add it themselves. On Pro, the user turns on developer mode under **Settings → Apps → Advanced settings**. **Symptom**: A whole category is missing from the agent's tool list, or a call answers "The Meetings module is not licensed for your Cogram account." **Likely cause**: Your organization is not licensed for that module. **Fix**: Check [Licensing](/organization-administration/licensing.md), then email about the module. Afterwards, have the agent list its tools again — or reconnect it — so the new tools appear. In a ChatGPT workspace, an admin must also refresh and republish the app. **Symptom**: Calls fail with `429 rate_limit_exceeded`. **Likely cause**: More than 50 requests in one minute for that user and application. **Fix**: Wait the number of seconds given in the `Retry-After` header. Have the agent request fewer, larger pages instead of many small calls. Email if the work genuinely needs a higher limit. **Symptom**: A working agent suddenly asks you to sign in again, or every call answers `401`. **Likely cause**: The refresh token expired, was revoked, or was overwritten by an older copy. **Fix**: Run the connection again — sign in and approve. For a headless agent, check that it saves the new refresh token after every refresh, and that only one process uses it. **Symptom**: The agent sees fewer projects or meetings than the user expects. **Likely cause**: The agent has exactly the user's own access. The user is not on those projects, or asset visibility hides those records from them. **Fix**: Add the user to the projects, or review [Asset Visibility](/projects/asset-visibility.md). Nothing about the connection itself can widen what the agent sees. **Symptom**: You need to cut off an agent that is already connected. **Likely cause**: Cogram has no per-agent disconnect screen. **Fix**: Remove the connector in the AI application that holds it. To stop every connected agent across the organization at once, turn off MCP access in [Organization Settings → Integrations](https://app.cogram.com/dashboard/settings/admin/integrations#mcp-access). ## Next steps * [Connecting AI apps](/integrations/connecting-ai-apps.md) — the user-facing connection steps. * [Cogram API](/integrations/cogram-api.md) — the REST API, for system-to-system integrations that need to write data. * [Licensing](/organization-administration/licensing.md) — which modules your organization is licensed for. * [Asset Visibility](/projects/asset-visibility.md) — how record-level visibility works. * [Agent](/agent/agent.md) — Cogram's own built-in agent, which needs no setup. Questions? Email or use the in-app Help menu. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cogram.com/integrations/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.