MCP Server

Model Context Protocol endpoint for AI agents: read and write the communities you manage.

The MCP server exposes nine tools — communities, events, and an onboarding write surface. Every tool acts with the caller's managed-community reach: a community you do not manage is simply not found. This page is the complete public reference an agent needs to build an integration — no sign-in required.

Endpoint & transport

  • POST https://local.foundation/mcp — JSON-RPC 2.0 requests, MCP Streamable HTTP.
  • GET https://local.foundation/mcp — the transport's server-sent-events stream; the client manages the session.
  • Protocol version 2025-03-26 — the server pins it and states it during initialize.
  • Requests are JSON. A standard MCP client (Claude Desktop, Cursor, your own) speaks the transport for you.

Authentication

Every request carries a bearer credential in the Authorization header. Use a personal API key (Profile → API Keys) — or an access token from the "Log in with Local Foundation" flow. The key carries your scopes, and each tool serves only the communities you manage.

Building the OAuth flow instead? Its discovery document is public at https://local.foundation/.well-known/openid-configuration — authorization code with PKCE.

  • Missing or invalid credential → 401.
  • Community-scoped API token → 403 community_scope_violation. MCP tools act with your full managed-community reach, so a community-bound token is not accepted. Use a personal credential.
  • A person is onboarded as a member by an agent — the agent itself authenticates as the developer who owns the key.

Client configuration

Paste this into an MCP client's server configuration and replace the key:

json 
{
  "mcpServers": {
    "local-foundation": {
      "url": "https://local.foundation/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-API-KEY"
      }
    }
  }
}

Tools

community_profile read

community_id

Read one of your communities: profile, member count, managers, tags, and the sandbox/draft flags.

list_community_events read

community_id

List a community's events — past and upcoming — with title, date, description and status.

get_event read

event_id

Read a single event by id.

search_onboarding_communities read

—

List the communities that opted in to receiving onboarding hand-offs — how an agent finds the right local community for a person.

get_member read

member_id

Read a member your agent created: profile, the signup data you collected, and the attributes you set.

create_member write · 20 / agent / hour

email (required), name, data

Create a member account. The platform emails a set-password link — no password passes through your agent. `data` carries your collected answers and is stored on the member's node.

set_member_attributes write · 120 / agent / hour

member_id, attributes

Merge structured attributes onto a member your agent created — onboarding answers now, certification status later.

add_member_to_community write · 60 / agent / hour

member_id, community_id

Hand a member your agent created over to a community you manage, under your manager authority — no member credential involved.

set_onboarding_opt_in write

community_id, accepts_handoffs

Opt one of the communities you manage in to (or out of) receiving onboarding hand-offs from agents.

Scoping

  • Reads and writes are reachable only for the communities you manage.
  • Anything outside that reach answers not found rather than 403 — the server does not leak whether an id exists.
  • A member another agent created is invisible to you: member reads and writes are scoped to your own provenance.

Rate limits

Surface Limit
/mcp endpoint (per IP) 120 requests / minute
create_member 20 / agent / hour
add_member_to_community 60 / agent / hour
set_member_attributes 120 / agent / hour

A 429 carries a Retry-After header (and x-ratelimit-* headers). Back off and retry; the write tools also report rate limit exceeded as a tool error.

Errors

  • 401 — no or invalid bearer credential.
  • 403 community_scope_violation — a community-scoped token was used against MCP.
  • 429 — rate limited (see above).
  • Tool-level not found — the id is outside the caller's scope, or does not exist. Read the error field; do not retry blindly.

Protocol exchange

MCP is JSON-RPC 2.0. initialize, then tools/list to discover the surface (each entry carries a title and MCP annotations), then tools/call:

json 
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"0.1.0"}}}
json 
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"community_profile","arguments":{"community_id":"<community-id>"}}}

Calls are always addressed by tool name and take their arguments under params.arguments — never a positional list.

REST fallback

MCP is the primary agent path; the REST API is kept as the fallback for clients that cannot speak it. Its machine contract is public: OpenAPI spec .

For agents

A machine-readable index of the platform — this page, the MCP endpoint, the OpenAPI spec and the OIDC discovery document — is served at /llms.txt so an agent can find its way in without being handed a URL.

Signed-in developers: the step-by-step onboarding walk-through lives in the Agent Integrations guide in the developer dashboard.