Setup & Usage Guide

Connect your AI assistant to your Raken account so you can ask natural-language questions about your projects and crew — and create or update projects and employees — without leaving the chat.

Estimated setup time: ~5 minutes.

1. What this is

Raken is a construction field-management platform. The Raken MCP Server connects your Raken account to AI assistants that speak the Model Context Protocol (MCP) — such as Claude (web, desktop, and mobile).

Once connected, you can ask your AI assistant about your Raken construction data in plain language and it answers by calling the Raken tools on your behalf. A small set of write tools let you create and update data, with a built-in confirmation step before anything changes. See the Tools reference for the full list of what's available.

The connection uses your own Raken sign-in — your AI assistant only ever acts as you, and only sees the data your Raken account can already see.

2. Connect your AI assistant to the server

The server uses OAuth 2.1 with Dynamic Client Registration — there is no API key to paste. Your AI assistant registers itself and walks you through a normal "Sign in with Raken" browser flow.

Copy the MCP endpoint URL from the server homepage.

In Claude (web — claude.ai)

1. Open Settings → Connectors.
2. Choose Add custom connector.
3. Paste the MCP endpoint URL. Give it a name you'll recognize (e.g. "Raken").
4. Click Add / Connect. Claude discovers the server's OAuth configuration and registers automatically.
5. A browser window opens on Raken's sign-in page. Sign in with your Raken credentials.
6. Approve the authorization request. The window redirects back to Claude and the connector shows as Connected.

Claude Desktop and mobile follow the same flow — Settings → Connectors → Add custom connector → paste the URL. The OAuth browser step is identical.

Your Raken account must have Raken MCP access enabled (depends on your plan tier and user permissions). If sign-in succeeds but the first tool call fails, see the Troubleshooting guide.

3. First call (smoke test)

In a chat with the connector enabled, ask:

"Who am I in Raken? Use the Raken connector."

Your AI assistant calls get_user_info and shows your user profile (first name, last name, email, user UUID, role, and company UUID). This confirms the end-to-end chain — AI assistant → MCP server → Raken — is working before you try anything heavier.

4. What you can do (the tools)

Ask in plain language — your AI assistant picks the right tool. A few examples:

"Which of my projects are active?"

"Show me all classifications."

"Create a new Raken project called 'Downtown Office', starting today."

"Add two new hires to the Downtown Office project: Marcus Delgado (Carpenter), Priya Raman (Laborer)."

"Who's assigned to the Downtown Office project?"

"Which checklists on the Downtown Office project haven't been completed?"

"Show me open observations on the Downtown Office project from the last 30 days."

The connector provides read tools (safe, non-mutating — projects, employees, work logs, time cards, checklists, observations, and more) and write tools (create a project, add a worker, update a project or an employee, and change project assignments in bulk). For the complete, always-current list see the Tools reference.

Write tools are confirmation-gated

Every write is protected by a server-side confirmation step. The first call never changes anything — it returns a PREVIEW — nothing was changed block showing exactly what would be sent, and your AI assistant must ask you to approve before calling again to actually commit the change. This is enforced by the server, not just a prompt, so you always get a chance to review.

Try it safely:

"Create a new Raken project called 'Downtown Office', starting today."

Your AI assistant shows the preview (nothing is created yet), then asks you to confirm. Approve to create it, or decline — either way you stay in control.

5. Tips for good results

• Mention "Raken" in your prompt when you want your AI assistant to use the connector — e.g. "List my Raken projects" — especially if you have other connectors enabled.
• Lists are paginated. A list comes back a page at a time; ask for "the next page" to keep going. The request allowance is shared with everyone at your company, so reading a long list end to end takes a while — narrowing the request (a status filter, a name search, a date range) is usually faster than paging through everything.
• Reference things by name. Your AI assistant will look up the underlying ID for you (e.g. "show the employees on the Downtown Office project"). For projects and employees, it uses a server-side query search rather than paging the full list — faster and cheaper than iterating pages, especially on large accounts. For employees, query also matches employee ID, email, and phone number.

6. Privacy & security

• Authentication is OAuth end to end. Your AI assistant connects to this server over OAuth 2.1 (Dynamic Client Registration + PKCE); the sign-in step itself runs against Raken's own OAuth authorization server, so you enter your credentials directly with Raken and your AI assistant never sees or stores your Raken password.
• The server keeps only what's needed to maintain the connection: your encrypted Raken sign-in tokens, and your Raken user ID, email address, and company ID. Your project, crew, time card, and checklist information isn't saved to the server's database — it's passed straight through to your AI assistant as you ask for it.
• The connector acts as you: it can only read and write the data your Raken account is already permitted to access. It cannot reach other companies' data, make admin or billing changes, or send arbitrary API requests.
• Every write requires explicit confirmation before it takes effect.
• You can disconnect the connector at any time from your AI assistant's connector settings (in Claude, Settings → Connectors). Once disconnected, it can no longer reach your Raken data; reconnecting re-runs the Raken sign-in.

Raken MCP access is an entitlement enabled per company by Raken — it is not on by default. get_user_info works without it (useful as a connection check), but every other tool requires it. If tool calls return a permissions error after a successful sign-in, contact Raken support to have Raken MCP access enabled for your company.

7. Reference

• Tools reference — every read and write tool and what it does
• Troubleshooting guide — connection issues and what 403 / 429 / 500 errors mean
• Raken app: app.rakenapp.com
• Raken support: support@rakenapp.com