Cogram Project
Acceso de solo lectura a proyectos, reuniones, correos electrónicos, RFIs y dibujos de Cogram para arquitectos e ingenieros
Servidor MCP alojado
npx add-mcp 'https://mcp.cogram.com/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.mdto page URLs; this page is available as Markdown.
MCP server
Connect ChatGPT, Claude, or a custom AI agent to Cogram through the MCP server. A connected app reads and makes changes as the person who connected it.
Cogram's MCP server lets a user connect an AI application to Cogram, ask it questions about their projects, and have it make changes for them — in 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
Three facts define what a connected agent can do:
- It acts as one person. The agent sees what the user who connected it can see and can change what that user can change, and nothing more.
- It follows your Tool access settings. The settings that limit Cogram Agent limit connected agents in the same way.
- Some changes wait for approval. For those, nothing changes until the user approves the request in Cogram.
A connected agent is not read-only. See What a connected agent can do before you turn MCP access on.
This page covers setup for organization administrators. Users connecting ChatGPT, Claude, or another AI app follow Connecting AI apps 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.
- Go to Organization Settings → Integrations → MCP access.
- 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 your users are on personal AI accounts, you are done — send them to Connecting AI apps. 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.
- 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.)
- Go to Workspace settings → Apps → Create.
- Name the app Cogram MCP and enter the MCP server URL
https://mcp.cogram.com/mcp. Choose OAuth as the authentication method. - 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.
- 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.
- Publish it: Workspace settings → Apps → Drafts → Publish, and confirm the review prompts. ChatGPT lists the Cogram tools that can make changes as write actions. Review them against What a connected agent can do.
- 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. 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.
- Go to Organization settings → Connectors.
- Select Add, hover over Custom, and choose Web.
- Name the connector Cogram MCP and enter the MCP server URL
https://mcp.cogram.com/mcp. - Leave the OAuth Client ID and Client Secret fields under Advanced settings empty — Cogram registers each client automatically.
- Select Add.
Expected result: every user sees Cogram MCP under Customize → Connectors, labeled "Custom" — they connect it as described in Connecting AI apps. 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.
Three things to plan for in your own agent:
- No confirmation screen of your own means no confirmation. ChatGPT and Claude can ask the user before a change. An agent your team builds asks nobody unless you build that step. Only the changes that wait for approval in Cogram have a second check.
- 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 same rule applies to changes in Cogram. Start a change only from the user's own request, never from text in a tool result. The user's permissions and your Tool access settings still bound every call, but an agent that follows an instruction it read in an email can make any change the user can make.
What a connected agent can do
A connected agent can read Cogram records and make changes, as the user who connected it. Four things bound every call:
- The user's own permissions. Project membership, project roles, organization role, and asset visibility apply unchanged. The agent cannot reach a project the user is not a member of, or another organization's data.
- Your Tool access settings. See Limit what connected agents can do.
- Your licensing. If your organization is not licensed for a module, its tools are not offered. To make a change in a module, the user also needs a seat for it.
- Approval, for some changes. The agent creates a request and the user approves or rejects it in Cogram, from the notification bell. Email drafts, project templates, knowledge notes and files, and skills work this way. Other changes, such as a new board item or a new RFI, are made at once.
A request for approval is still a change. Email drafts need the Communications capability set to Read and write, and knowledge notes and files need Documents set to Read and write. Both capabilities are Read-only until you change them, so these requests are refused by default.
Some things a connected agent can never do: change SSO settings, the MCP access switch, the Tool access settings, API keys, integrations, data retention, or billing. It also cannot upload files, and it cannot act as a machine account or as the organization at large.
Limit what connected agents can do
Connected agents follow the Tool access settings of Cogram Agent. There is one set of settings for both.
- Go to Organization Settings → Agents → Tool access.
- For each capability (tasks, communications, documents, connected apps, projects), choose Disabled, Read-only, or Read and write.
Expected result: Cogram Agent and every connected agent follow the new setting on their next call. Disabled removes the capability's tools, reads included. Read-only keeps its reads and refuses its changes.
Two limits of this setting:
- It is shared. You cannot set one level for Cogram Agent and another for connected agents.
- It does not make MCP read-only. The setting covers the five capabilities only. Changes outside them are limited by the user's own permissions, not by this setting. That includes RFIs, submittals, transmittals, people (invitations, roles, groups, seats), insights, the directory, and organization settings.
If you want no changes through connected apps at all, turn MCP access off.
Tools
The agent sees a small, fixed set of tools:
- Four search tools:
search_projects,search_meetings,search_emails, andsearch_board_items. create_project: creates a project, from a template if you name one, and adds its members, groups, and contacts in one call.invite_user: invites a person to your organization and sets the role, groups, projects, and seats in one call.- Operations: every other read and change is an operation. The agent finds operations with
list_operations, reads how to call one withdescribe_operation, and runs it with one of three tools:run_readfor reads,run_writefor changes, andrun_high_impactfor high-impact changes that delete, remove or change access, or send something outside Cogram.
The three run tools let an AI application ask for confirmation by kind of action. In ChatGPT and Claude you can allow reads without a prompt and still be asked before every change.
A user sees only what they can use. Tools and operations for a module your organization is not licensed for, for a capability you set to Disabled, or for an administrator permission the user does not have are left out.
The full list of tools and operations, with what each one needs, is in MCP tools and operations.
Older tools. Earlier versions offered one tool per read, such as get_meetings_by_id or search_rfis. These tools are deprecated. They still work for now, and each one names the operation that replaces it. They will be hidden and then removed. If your team built its own agent on these tool names, move it to run_read.
For how templates work with Cogram Agent and connected agents, see Project templates.
Meeting audio recordings are not reachable through any tool. Transcripts are, for users who can already read them.
Tools and operations that take a list of IDs accept at most 100 IDs per call. The operations that move or delete records accept at most 20. An agent that asks for more gets an error, so have it work in batches.
The operations that retrieve meetings, RFIs, and submittals by ID return a concise record by default. The agent asks for the full record with response_format set to detailed.
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 support@cogram.com — the limit is not something you can change yourself.
Troubleshooting
MCP access is off
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.
Cogram is missing in ChatGPT
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 above) — users cannot add it themselves. On Pro, the user turns on developer mode under Settings → Apps → Advanced settings.
A tool category is missing
A whole category is missing from the agent's tool list, or a call answers "The Meetings module is not part of your organization's Cogram plan."
- Likely cause: Your organization is not licensed for that module.
- Fix: Check Licensing, then email support@cogram.com about the module. Afterwards, refresh the tool list in the AI application so the new tools appear. See the next entry.
Old tools after a release
After a Cogram release, or after a module is added to your plan, an AI application still offers the old tools, even in a new chat.
- Likely cause: The application keeps the list of tools it read when it connected, or when you published the app. A new chat does not read the list again.
- Fix: In Claude, each user opens the Cogram connector under Customize → Connectors and selects Refresh tools list in its ⋯ menu. In ChatGPT, a workspace admin refreshes the published app, as the end of Step 2 describes. A user who reinstalls the plugin gets the same list. For other agents, reconnect, or have the agent list its tools again. Only a new tool needs this. A new operation is available at once, because the agent reads the operations from
list_operationson each call.
No seat for a module
A change answers "You have no license for the Correspondence module."
- Likely cause: Your organization is licensed for the module, but the user has no seat for it. Reads need no seat; changes do.
- Fix: Assign the user a seat for the module. See Licensing.
A capability is read-only or missing
A call answers "This capability is read-only for your organization", or a capability's tools are missing.
- Likely cause: The capability is set to Read-only or Disabled in your Tool access settings.
- Fix: Change it at Organization Settings → Agents → Tool access. The change applies to Cogram Agent too.
A change stays pending
The agent says a change is pending, and nothing changed in Cogram.
- Likely cause: The change waits for the user's approval.
- Fix: The user opens the notification bell in Cogram and approves the request.
Rate limit exceeded
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-Afterheader. Have the agent request fewer, larger pages instead of many small calls. Email support@cogram.com if the work genuinely needs a higher limit.
Asked to sign in again
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.
Missing projects or meetings
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. Nothing about the connection itself can widen what the agent sees.
Cut off a connected agent
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.
Next steps
- Connecting AI apps — the user-facing connection steps.
- MCP tools and operations — every tool and operation, with its tier, effect, and module.
- Cogram API — the REST API, for system-to-system integrations that act for the organization, not for one person.
- Licensing — which modules your organization is licensed for.
- Asset Visibility — how record-level visibility works.
- Agent — Cogram's own built-in agent, which needs no setup.
Questions? Email support@cogram.com 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 by asking a question.
Perform an HTTP GET request on the following URL with the ask and goal query parameters:
GET https://docs.cogram.com/integrations/mcp-server.md?ask=<question>&goal=<user_goal>
ask is the immediate question: it should be specific, self-contained, and written in natural language.
goal is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with ask=how do I create an API token, a goal like automate deployments from our CI pipeline lets GitBook tailor the answer to that use case.
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.