Connect Claude to Giraffe and your AI assistant can work inside your live project. Ask it to check a site's yield, change a usage, or pull data from another tool into your plan, and it makes the change in the project you have open. Claude keeps everything else it can reach, like your files, email, and other connectors, so it can bring that context into your feasibility work.

The Giraffe MCP is in beta. Its tools and setup steps change as we test and improve it. Reach out to your account team to try it out!

What an MCP is

MCP stands for Model Context Protocol. It's an open standard that lets an AI assistant connect to outside tools and data. An MCP server is a plug-in for your AI assistant. It tells the assistant which actions it can take in another product, and carries out those actions when the assistant asks.

The Giraffe MCP server is that plug-in for Giraffe. Add it to Claude, and Claude can read and change the Giraffe project open in your browser, alongside every other tool it already uses.

When to use the MCP instead of Giraffe AI

Use the Giraffe MCP when your work reaches outside Giraffe. Giraffe AI lives inside Giraffe and works with your project. The MCP brings your project to the AI assistant you already use, along with everything else that assistant can reach.

Work in the interface you already know. Claude's own app gives you a full-size chat, conversation history, file uploads, and the habits you've already built. You don't need to learn a new chat panel.
Combine Giraffe with your other tools. Claude can pull numbers from a spreadsheet, read a planning PDF, or check an email thread, then apply what it finds to your site in Giraffe.
Keep your own setup. Claude keeps your other connectors, files, and saved instructions, so you don't repeat context for each project.
Use Claude Code. Work from your terminal and combine Giraffe with scripts, data files, and your own app code.
Call your apps' tools. Claude can use tools that your own Giraffe apps advertise.

Use Giraffe AI when you want a quick answer or change inside Giraffe, with nothing to install.

What the Giraffe connector does

The Giraffe MCP lets Claude work in two ways: directly with Giraffe, and through the tools your Giraffe apps offer. Claude can also combine either one with the other connectors and files it already uses.

🚨 Warning: Claude makes real changes to your project through the Giraffe SDK. Try it on a copy of a project first, and take extra care with any request that affects your whole workspace.

Work directly with Giraffe

Claude can run the same commands a Giraffe app can run, about 300 in all. It looks up each command in the SDK docs before it runs it. Claude can:

Read your project, including the boundary, drawn geometries, usages, levels, and areas.
Draw, edit, and delete geometries and change their properties and usages.
Change what you see without saving anything, like zooming the map, selecting or highlighting geometries, showing a temporary layer, or opening a popup.
Change one item in a larger record, like a single usage, and check first that nobody else changed it.

Use tools from your Giraffe apps

Giraffe apps can offer their own tools to Claude. Claude lists the tools from every app open in your project and calls the one it needs. For example, a stormwater app can offer a tool that screens the selected parcel against flood, wetland, and water quality layers. An app offers tools only when its developer has set it up to advertise them, and Claude only sees an app's tools while that app is open in a panel.

Combine Giraffe with your other tools

Claude keeps every other connector and file it can reach. In one request, Claude can read a planning PDF, pull rents from a spreadsheet, apply the controls to your massing in Giraffe, and write the results back to your spreadsheet.

Claude acts as you, in the browser tab where your project is open. It can only do what you can already do in that project. The tools Claude can use change as the connector develops.

To make your own app's tools available to Claude, follow the giraffe-app-mcp repository.

Add the MCP app to your Project

Add the Giraffe connector once in each Claude product you use. claude.ai and Claude Code each need their own setup.

Open your Giraffe project in your browser.
Add the MCP app to your project from the App Library and open it in its own panel.

Connect the MCP app to Claude

Click Connect in the MCP app. This links your browser to your Giraffe account.

The Connect link lasts 30 minutes. If Claude says your browser isn't linked, click Connect again and retry the sign-in.

Then, connect to Claude either via the Terminal or in the browser

Claude’s own instructions

Claude Code with MCP servers: https://code.claude.com/docs/en/mcp
Custom connectors in claude.ai: https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp

Using Terminal to Connect in Claude Code

1. Open a terminal

Mac: press Cmd+Space, type Terminal, and press Enter.
Windows: press the Windows key, type PowerShell, and press Enter.

2. Check that Claude Code is installed

Type this and press Enter:

claude --version

If you see a version number, it’s installed. If you get “command not found”, install it using the Claude Code setup guide.

3. Add the Giraffe MCP

Paste this and press Enter:

claude mcp add --transport http --scope user giraffe-app https://mcp-relay.giraffe.build/mcp

--scope user makes the connection available in every folder you open Claude Code in, not just the current one.

4. Sign in

In the terminal, type claude and press Enter to start Claude Code.
Type /mcp, pick giraffe-app, and follow the sign-in prompt in your browser.

5. Check it worked. Ask Claude “Is Giraffe connected?”

Connect to Claude.ai (web browser)

Go to claude.ai and click your name or initials in the bottom left.
Click Settings, then Connectors.
Click Add custom connector.
Enter a name, like Giraffe.
Paste this in the URL field: https://mcp-relay.giraffe.build/mcp
Click Add.
Click Connect next to the Giraffe connector, and approve the sign-in in the window that opens.
Start a new chat. Click the + or tools button under the message box and check that Giraffe is turned on.
Ask Claude “Is Giraffe connected?”

On a Claude Team or Enterprise plan: an organization owner may need to add the connector first, under Organization settings, then Connectors. After that, each person clicks Connect to sign in.

Add the Giraffe SDK skill

The Giraffe SDK skill helps Claude make correct changes through the Giraffe MCP. It tells Claude where the SDK docs are and how Giraffe stores a project. With the skill, Claude:

Checks each SDK command and its arguments against the official docs.
Edits the geometries you draw, and treats the areas and heights Giraffe calculates from them as read-only.
Passes map positions as longitude and latitude.
Changes a usage when you want many geometries to change at once.
Looks up flow nodes in the docs before it builds or changes a flow.
Suggests searching the Content Library for a usage, flow, or block that isn't in your project.

To install it in Claude Code:

Download the Giraffe SDK skill file.

Download the skill.md file
Create a folder named giraffe-sdk-developer inside your Claude Code skills folder:
- Mac: ~/.claude/skills/giraffe-sdk-developer
- Windows: %USERPROFILE%\.claude\skills\giraffe-sdk-developer
Move the downloaded file into that folder and name it SKILL.md.
Start a new Claude Code session so it loads the skill.

In claude.ai, upload the skill file under Settings, then Capabilities, then Skills.

The same skill helps Claude develop a Giraffe app with AI.

Check that Claude is connected

Ask Claude "Is Giraffe connected?" Claude checks the connection and tells you the next step if something is missing. Common fixes:

No browser session attached. Open your Giraffe project and the app panel, then click Connect in the MCP app.
Two workspaces connected. Click Set Active Workspace in the app panel of the workspace you want Claude to use.

Ask Claude to work in your project

Describe the result you want in plain language. Claude reads the project first, then makes the change. Try prompts like these:

"List every building in this project with its usage, levels, and gross floor area."
"Change the usage of the selected building to Residential and add two levels."
"Check every building against a 24 m height limit and tell me which ones go over."
"Zoom the map to the project boundary and turn on the flood zones layer."

Claude works on the project open in your browser. Keep that tab open, with the MCP app open in a panel, while Claude works. A small panel in the bottom left keeps the MCP app out of the way.

Write good prompts for the Giraffe MCP

A good prompt tells Claude what to look at, what to change, and when to stop and check with you. Clear prompts keep your feasibility numbers accurate and stop Claude from changing geometries you meant to keep.

Name what to change. Say which geometries, usages, or layers you mean, like "the three buildings with the Residential usage." Select geometries in Giraffe first and say "the selected geometries" to point at them.
Ask Claude to read before it writes. Start with "Show me what you plan to change before you change it." Claude lists the changes, and you approve them.
Work in small steps. Ask for one change at a time and check it on the map before you ask for the next. A small change is easier to spot and undo.
Give the numbers. Include your targets and controls, like a 24 m height limit, a 3:1 FAR, or 120 units. Claude uses your numbers instead of guessing.
Open the apps Claude needs. Claude only uses an app's tools while that app is open in a panel. Open it in its own panel, then say which app to use, like "Use the stormwater app to screen the selected parcel."
Point to your other sources. Name the file, spreadsheet, or connector that holds the data, like "Use the rents in Feasibility.xlsx."
Keep requests to your project. Ask for changes to the open project. Check with your team before you ask Claude to change anything that affects the whole workspace.

Here's a prompt that follows these tips:

Read the planning controls in Site 14 controls.pdf. Check every building in this project against the height limit and FAR. List any that go over and show me the change you'd make to fix each one. Don't change anything until I approve.

If a request stops partway through, check your project before you ask Claude to try again. Claude can't always tell whether the change was saved.

Troubleshoot the Giraffe MCP connection

Most Giraffe MCP connection problems come from the MCP app closing, the browser blocking the link to Claude, or a workspace mix-up. Ask Claude "Is Giraffe connected?" first. Claude reports what's connected and the next step.

Claude says no Giraffe session is connected

The MCP app must stay open in a panel for Claude to reach your project. Reloading the page or switching to another app in the same panel closes the MCP app and drops the connection.

Open your Giraffe project.
Open the MCP app in its own panel.
Click Connect.

If the connection drops for less than 5 minutes in the same workspace, the MCP app reconnects on its own.

Claude says an app isn't open

Claude can only use an app's tools while that app is open in a panel. Giraffe shows one app per panel, so opening another app in the MCP app's panel closes the MCP app. Put the MCP app and the app you need in separate panels.

Claude says two workspaces are connected

Claude won't guess which workspace to use when projects from two workspaces are open. Click Set Active Workspace in the MCP app of the workspace you want.

Sign-in fails or Claude says your browser isn't linked

The link from Connect lasts 30 minutes. Click Connect again, then add or re-authenticate the connector in Claude right away. claude.ai and Claude Code each need their own sign-in, so you may need to click Connect once for each.

Browser extensions and settings that block the connection

The Giraffe MCP runs on mcp-relay.giraffe.build and mcp-control.giraffe.build. Some browser extensions and settings block these addresses or the sign-in pop-up. If Connect does nothing or the connection keeps dropping:

Allow pop-ups for Giraffe.
Pause ad blockers and privacy extensions, like uBlock Origin or Privacy Badger, for giraffe.build.
Try a browser profile with no extensions.
On a company network, ask your IT team to allow mcp-relay.giraffe.build and mcp-control.giraffe.build.

A request failed partway through

If the connection drops while Claude is changing your project, Claude can't tell whether the change happened. Check your project before you ask Claude to try again, so the change isn't applied twice. Claude also stops waiting on any single step after 30 seconds.