Falaah Falaah AI

MCP Server · Connect AI Assistants

Connect Claude and other MCP-compatible AI assistants to your Muin data using the built-in Model Context Protocol server.

Muin ships a built-in Model Context Protocol (MCP) server. Any MCP-compatible AI assistant, such as Claude or your own agent built on an MCP client library, can connect to it and work with your organization’s documents, finances, HR compliance, vendors, and workflows, scoped to your organization only.

What You Can Do

Once connected, your AI assistant can answer questions like:

  • “Which invoices are overdue, and what’s our month-to-date spend?”
  • “Find the signed lease agreement and summarize the renewal terms.”
  • “Which staff certifications expire in the next 60 days?”
  • “What’s pending my approval, and what does this workflow’s progress look like?”

The assistant calls Muin’s MCP tools behind the scenes and grounds its answers in your live data. See the MCP Tools Reference for the full tool list.

Setting Up

1. Point Your MCP Client at Muin

The MCP endpoint is:

POST https://muin-api.falaah.ai/api/v1/mcp

Configure your client with that URL and no Authorization header. The first time it connects, Muin opens its approval screen; click Allow access there and the connection is made. There is no key to create, copy, or store. What the approval screen shows, and what to do if it fails, is in Connecting and Authorizing.

The connection carries your own permissions. It can see what you can see, and nothing more, so it stops working the moment your access does. You can review and end any connection at Settings → Integrations → Connected Apps.

2. Where There Is No Browser to Sign In With

Claude Code, CI, and headless boxes cannot complete a sign-in, so those use an API key instead:

  1. In Muin, go to Settings → Integrations → API Keys.
  2. Click Create API Key and give it a descriptive name (e.g., “Claude Code”).
  3. Grant it Read scope. The MCP server requires it. Add Write only if the assistant should record contributions or advance workflows.
  4. Copy the key immediately. It won’t be shown again.

Then send it as a Bearer token:

Authorization: Bearer muin_your_api_key_here

An API key is a standing credential that outlives your session, so prefer signing in wherever a browser is available.

The server speaks JSON-RPC 2.0 and supports the standard MCP handshake (initialize, tools/list, tools/call, ping).

3. Verify the Connection

Ask your assistant to list its available Muin tools. You should see tools prefixed nonprofit_, documents_, finance_, hr_, workflows_, and grounding_, for the modules your organization has turned on. If the connection fails, check:

Symptom Cause Fix
401 Unauthorized Missing, malformed, revoked or expired credential On a key, the header must be Authorization: Bearer muin_.... On a sign-in connection, connect again and approve
403 Access denied Key lacks the read scope, or a write tool was called on a read-only connection Recreate the key with the scope it needs, or reconnect with write access
429 Rate limit exceeded More than 60 MCP calls in a minute on one connection Slow the agent down, or use a separate connection per agent

Security Model

  • Tenant-scoped. A connection or key only reaches the organization it was approved or created in. There is no cross-organization access.
  • Read-first. Most tools only read. The few that write, each marked in the MCP Tools Reference, require the connection to carry write access, and a read-only connection cannot call any of them. If you do not want your assistant writing at all, connect it read-only.
  • Revocable. Revoke access in Settings → Integrations → Connected Apps ends a sign-in connection immediately. For a key, revoke it in Settings → Integrations → API Keys.
  • Auditable. Pass an optional X-Agent-Identifier header to tag which agent made each call in audit logs. This helps when several assistants share an integration.

Rate Limits

MCP calls are rate limited per connection: 60 calls per minute. Exceeding the limit returns HTTP 429 with a clear message.

That figure is the platform’s fail-closed default, applied because no explicit limit is configured for the mcp.tools endpoint. It is what the server enforces today.

Next Step