> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trebellar.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trebellar.app/_mcp/server.

# MCP Server

Trebellar runs a **Model Context Protocol (MCP) server** that lets AI assistants — Claude,
ChatGPT, or any other MCP-compatible client — query your portfolio directly in
conversation. Once connected, an assistant can look up buildings and floors, chart
attendance trends, forecast occupancy, and analyze attrition, all without any custom
integration code on your side.

> **Tip**
>
> Not sure what MCP is? It's an open standard for connecting AI assistants to external
> tools and data sources. If your assistant supports "connectors," "tools," or "MCP
> servers," it can connect to Trebellar.

## Connecting a client

The Trebellar MCP server is a remote server reachable over **Streamable HTTP** — there's
nothing to install or run locally.

|                |                                         |
| -------------- | --------------------------------------- |
| **Server URL** | `https://[org_id].trebellar.app/mcp`    |
| **Transport**  | Streamable HTTP                         |
| **Auth**       | OAuth 2.1 (dynamic client registration) |

Steps:

1. In your MCP client, add a new remote server/connector and enter the URL above,
   substituting your organization's ID — the same `[org_id]` used in your
   [SSO](/sso) and SCIM endpoints.
2. The client will register itself with Trebellar automatically and redirect you to
   sign in. Use your normal Trebellar credentials, or your identity provider if
   [SSO](/sso) is enabled for your org.
3. Review the requested scopes and authorize the connection.

Once authorized, the assistant can call any of the tools described in the
[Tools reference](/mcp-tools).

> **Note**
>
> No manual API keys or client secrets are involved — authorization happens through the
> same login your team already uses to access Trebellar, and access is scoped to
> whatever that account can see in the product.

### Supported clients

Any client that speaks MCP over Streamable HTTP and supports OAuth 2.1 will work,
including:

| Client                        | Notes                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| Claude (Desktop, web, mobile) | Add as a custom connector                                                               |
| Claude Code                   | Add with `claude mcp add --transport http trebellar https://[org_id].trebellar.app/mcp` |
| ChatGPT                       | Add as a custom connector (requires a plan with connector support)                      |
| Other MCP clients             | Any client supporting the Streamable HTTP transport                                     |

## What you can ask

Once connected, you can ask your assistant things like:

* "Which buildings do we have in the EMEA region, and what's their capacity?"
* "Show me monthly attendance for our Austin HQ over the last year."
* "What's the forecasted attendance rate for the 3rd floor next month, broken out by
  business day?"
* "How much headcount did the Engineering group lose to attrition and to transfers in
  each of the last four quarters?"

The assistant translates these into calls against the tools in the
[Tools reference](/mcp-tools) — it decides which tool(s) to call and with which
parameters based on your question.

## Data access and scope

MCP tools only return data the authenticated user is already entitled to see in
Trebellar — connecting an assistant doesn't widen access beyond what that person's
account already has in the product.

Most tools accept an optional `fromAssetIds` array to scope a query to specific
buildings, floors, or spaces. Leaving it empty (or omitting it) is a reference to your
**entire portfolio**, so be specific if you want the assistant to focus on a subset.
Some tools also accept an `assetLocationGroup` instead, which lets you refer to a named
grouping — a campus, site, city, or region — without first looking up the underlying
asset IDs.

## Interactive results (MCP Apps)

Some tools link a **UI resource** alongside their data. In a client that supports MCP
Apps (such as Claude), the result renders as an interactive component instead of raw
JSON or a text summary.

Today, [`get_monthly_building_attendance`](/mcp-tools#get_monthly_building_attendance)
links a bar-chart UI resource — clients that don't support MCP Apps simply fall back to
the underlying data. More tools will gain linked UI resources over time; each one is
called out in the [Tools reference](/mcp-tools).

## Need help?

If you run into trouble connecting a client or have a question about tool access,
reach out to your account rep — we're happy to help at any stage of the process.