Introduction to Mapped MCP

Getting Started with Mapped MCP

Mapped Model Context Protocol (MCP) gives your agentic applications seamless, easier access to the Mapped data about your buildings. This guide walks you through what it is, how to set it up, and a few things you can build with it.

What is Mapped MCP?

Mapped MCP is a Model Context Protocol server that connects your agentic applications — chat bots, scheduled agentic analysis, in-house app development — to your building data on Mapped.

Its job is to translate human language into Mapped GraphQL queries, so your agent can get the data it needs without fully understanding our GraphQL, and to help it write GraphQL more correctly when it does. By guiding the agent instead of leaving it to guess, Mapped MCP reduces hallucination and improves accuracy overall.

The current MCP supports two sets of tools:

• GraphQL generation & execution: generate a Mapped GraphQL query from a natural-language request, and optionally run it against the Mapped API and return the results.
• Ontology navigation: explore the Mapped ontology: walk the entity-type hierarchy, search entity types by tag, and fetch a type's full definition (properties, relationships, and parents).

Your application takes it from there. Use the returned data for whatever business logic you care about.

How to Use MCP

1. Sign up

Create a Mapped account at mapped.com. This gives you access to the Console, where the rest of the setup happens.

2. Enable the Sandbox and get familiar with the data

Before connecting anything, spend a few minutes with Mapped's read-only demo data. In the Console, turn on Sandbox Mode from the top menu bar and switch to the TenantyWorks (Sandbox) organization. You can browse the data directly in the GraphQL Explorer — no extra credentials needed.

See Enabling & Using the Sandbox for the full walkthrough. Getting a feel for the shape of the data here will make everything that follows easier.

3. Create a Personal Access Token (PAT)

Mapped MCP authenticates each request with a Personal Access Token. In the Console, create a PAT and copy it somewhere safe — you'll paste it into your client's configuration in the next step.

For details on PATs and how Mapped auth works, review Authentication & Security.

4. Add Mapped MCP to your agent

Mapped runs a hosted MCP instance at https://mcp.mapped.com/mcp, so you don't need to run anything yourself. Just point your client at it and supply your PAT. There are two ways to connect.

4.1 An easy way — Claude plugins

If you use Claude Code, the mapped/claude-plugins repo is a plugin marketplace that wires everything up for you:

Copy
1
2
/plugin marketplace add mapped/claude-plugins
/plugin install mapped-mcp@mapped

Then provide your PAT. Never put the token in the plugin manifest. Instead, supply the PAT through your own config. The recommended way is a project-local .claude/settings.local.json (Claude Code keeps this out of git):

Copy
1
2
3
4
5
{
  "env": {
    "MAPPED_PAT": "your-mapped-pat"
  }
}

The same env block works in ~/.claude/settings.json to apply it across all your projects, or you can export it for a one-off session:

Copy
1
export MAPPED_PAT=<your-mapped-pat> && claude

The plugin sends Authorization: token ${MAPPED_PAT} on every call and expands ${MAPPED_PAT} from your environment at connect time, so the manifest stays secret-free. See the plugin README for the full reference, including Claude on the web (claude.ai/code) and secret-manager setups.

4.2 A generic way — add it as an MCP server

Any MCP-capable client can connect to the same hosted endpoint. In every case, the three pieces are the same:

• Transport: streamable HTTP
• URL: https://mcp.mapped.com/mcp
• Header: Authorization: token <your-mapped-pat>

Claude Code — add it from the CLI (single quotes keep ${MAPPED_PAT} as a reference that Claude Code expands from your environment at connect time):

Copy
1
2
claude mcp add --transport http mapped https://mcp.mapped.com/mcp \
  --header 'Authorization: token ${MAPPED_PAT}'

OpenAI Codex — add a server block to ~/.codex/config.toml:

Copy
1
2
3
[mcp_servers.mapped]
url = "https://mcp.mapped.com/mcp"
http_headers = { Authorization = "token <your-mapped-pat>" }

Other clients — clients that accept a JSON MCP config (Cursor, VS Code, and others) use the same shape:

Copy
1
2
3
4
5
6
7
8
9
10
11
{
  "mcpServers": {
    "mapped": {
      "type": "http",
      "url": "https://mcp.mapped.com/mcp",
      "headers": {
        "Authorization": "token ${MAPPED_PAT}"
      }
    }
  }
}

Wherever your PAT ends up stored in plain text, treat it like a password and keep it out of source control.

5. Start a session and ask

Once the server is connected, start a session and just ask in plain language. Your agent will call the Mapped MCP tools behind the scenes to generate the query, run it, and hand back the data. Try something like List the buildings in my organization to confirm everything is wired up.