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
| Capability | Notes |
|---|---|
| Core tools | Search, get/create places, lists, want/been status |
| Module tools | Optional tools from modules you install (zip or GitHub) |
| Auth | Bearer PAT (plc_…) — same privacy rules as the UI |
| Transport | Streamable 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
- Open Placard → Settings → MCP.
- Create a personal access token and copy it once.
- Note your MCP URL:
https://your-domain/mcp(same origin as the app). - 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):
| Tool | Purpose |
|---|---|
search_places | Text / tag / list / type / open now or tonight / radius |
get_place | Card-level detail and key facts |
create_place | Save from a Google Place ID or coordinates |
list_lists | List your lists |
add_to_list | Add a place to a list |
set_status | Want 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:
| Module | Local name | Name agents call |
|---|---|---|
Pick (places.pick, sibling placard-places-pick) | pick_place | places_pick__pick_place |
Skeleton (example.skeleton) | skeleton_hello | example_skeleton__skeleton_hello |
Module tools are not part of the core MCP set. The host loads a module and exposes its tools when:
- The module is installed and enabled for the instance
- 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
Related
- Install — Compose / Coolify / Dokploy
- Creating modules — ship your own tools
- FOR AI — module brief — copy-paste prompt for agents that write modules