Connect agents with MCP

Placard exposes a Model Context Protocol endpoint on your instance so tools like Cursor or Claude can search your library, add places, and run installed module tools using a personal access token you control.

What you get

CapabilityNotes
Core toolsSearch, get/create places, lists, want/been status
Module toolsOptional tools from modules you install (zip or GitHub)
AuthBearer PAT (plc_…) — same privacy rules as the UI
TransportStreamable HTTP at $PUBLIC_URL/mcp

Anyone with a token can read and change your places. Treat it like a password.

Search and get follow the same household rules as the UI when household mode is on. There are no MCP tools yet to share a place or change visibility.

Connect a client

  1. Open Placard → Settings → MCP.
  2. Create a personal access token and copy it once.
  3. Note your MCP URL: https://your-domain/mcp (same origin as the app).
  4. Add that URL + Bearer token in your MCP host (Cursor, Claude Desktop, …).

Example Cursor-style config shape (adjust to your client’s schema):

{
  "mcpServers": {
    "placard": {
      "url": "https://placard.example.com/mcp",
      "headers": {
        "Authorization": "Bearer plc_your_token_here"
      }
    }
  }
}

Disable MCP for the whole instance with MCP_ENABLED=false in the server environment.

Core tools

Agents call these names directly (no module prefix):

ToolPurpose
search_placesText / tag / list / type / open now or tonight / radius
get_placeCard-level detail and key facts
create_placeSave from a Google Place ID or coordinates
list_listsList your lists
add_to_listAdd a place to a list
set_statusWant to go / been there

Module tools

Installed modules may register extra tools. Placard prefixes them so names never collide:

{module_id_with_dots_as_underscores}__{local_tool_name}

Examples after you install those modules:

ModuleLocal nameName agents call
Pick (places.pick, sibling placard-places-pick)pick_placeplaces_pick__pick_place
Skeleton (example.skeleton)skeleton_helloexample_skeleton__skeleton_hello

Module tools are not part of the core MCP set. The host loads a module and exposes its tools when:

  1. The module is installed and enabled for the instance
  2. You allow MCP for that module under Settings → Marketplace → [module] → Settings

Settings lists the global tool names (what agents should call).

Safety

  • Prefer short-lived tokens; revoke unused ones in Settings → MCP
  • Destructive core actions (delete) are not exposed as MCP tools today
  • Turn off Allow MCP for this module to hide that module’s tools without uninstalling