MCP Setup

Use Configure with Claude Desktop, Cursor, or any MCP-compatible client.

Quick Start

1. Authenticate:

npx configure-mcp login

This opens your browser. Sign in with Google/GitHub, enter your agent name to get an API key, then verify your phone number. Your credentials are saved to ~/.configure/.

2. Add to your MCP client config:

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "configure": {
      "command": "npx",
      "args": ["-y", "configure-mcp"]
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "configure": {
      "command": "npx",
      "args": ["-y", "configure-mcp"]
    }
  }
}

No env vars needed — the MCP server reads credentials from ~/.configure/. You can override with env vars if preferred (see Environment Variables).

3. Restart your MCP client. You'll see Configure tools in the tools menu.

How Authentication Works

Configure uses phone-based identity federation. Your phone number is how Configure identifies you across all agents — same phone, same profile, same memory.

When you ran npx configure-mcp login, two things happened:

• Developer auth (Google/GitHub): Created your developer account and API key
• Phone verification: Created your federated user profile

The API key identifies your agent. The phone-verified token identifies you as a user. Together, they unlock all Configure tools.

Two Scopes

Scope	Auth	What it does
Agent self	API key only	Your agent's own identity, memory, skills, and notes. Read-only by default.
User profile	API key + phone-verified token	Your profile — identity, preferences, connected tools (Gmail, Calendar, Drive, Notion), memories across all agents.

If you skipped phone verification during npx configure-mcp login, only agent self tools are available. Run npx configure-mcp login again to complete verification.

Available Tools

All tools use a configure_ prefix in MCP.

Agent Self Tools (API key only)

Your agent's own persistent filesystem — its identity, accumulated knowledge, and configuration.

Tool	Description
configure_self_get_profile	Get your agent's assembled profile: soul, config, skills overview, memory summary
configure_self_get_memories	Get your agent's memory entries with optional date filtering
configure_self_read	Read from a specific path in your agent's filesystem
configure_self_ls	List files and directories in your agent's filesystem
configure_self_search	Search your agent's filesystem by keyword
configure_self_remember	Save a fact to your agent's memory

User Profile Tools (requires phone verification)

Your profile as a user — shared across every agent you use.

Tool	Description
configure_get_profile	Get your full profile (identity, preferences, integrations, agents, summary)
configure_remember	Save a fact or preference to your memory
configure_get_memories	Query your memories with agent and date filters
configure_ingest	Extract and save memories from conversations or text
configure_profile_read	Read specific data by path
configure_profile_ls	List files and directories in your profile
configure_profile_write	Write to your profile (scoped to agent namespace)
configure_profile_search	Full-text search your profile
configure_profile_rm	Delete from your profile (scoped to agent namespace)
configure_get_documents	Get auto-generated user identity documents
configure_generate_documents	Regenerate user identity documents

Search Tools (requires phone verification)

Search your connected tools. Results are saved to your profile automatically.

Tool	Description
configure_search_emails	Search Gmail with query operators
configure_get_calendar	Get calendar events (today, tomorrow, week, month)
configure_search_files	Search Google Drive
configure_search_notes	Search Notion workspace
configure_search_web	Search the web (always available, no connection needed)
configure_fetch_url	Fetch a web page's content by URL (always available)

Action Tools (requires phone verification)

Tool	Description
configure_create_calendar_event	Create a Google Calendar event
configure_send_email	Send an email via Gmail

Environment Variables

Override ~/.configure/ credentials or configure advanced options:

Variable	Required	Default	Description
CONFIGURE_API_KEY	No*	From ~/.configure/credentials	Your API key
CONFIGURE_USER_TOKEN	No*	From ~/.configure/token	Your phone-verified JWT
CONFIGURE_USER_ID	No	—	Your own user identifier (alternative to token — see Server-side users)
CONFIGURE_SELF_WRITE	No	false	Enable agent self-write tools (self_write, self_rm, self_remember)
CONFIGURE_API_URL	No	https://api.configure.dev	Custom API endpoint

*Required if ~/.configure/ credentials don't exist.

Set either CONFIGURE_USER_TOKEN (phone-authenticated) or CONFIGURE_USER_ID (server-side). If neither is set, the MCP server runs in agent-only mode.

Self Write Mode

By default, the LLM can only read your agent's data. To allow the LLM to write to your agent's memory and filesystem, set:

{
  "mcpServers": {
    "configure": {
      "command": "npx",
      "args": ["-y", "configure-mcp"],
      "env": {
        "CONFIGURE_SELF_WRITE": "true"
      }
    }
  }
}

This adds three tools: configure_self_write, configure_self_rm, configure_self_remember.

When to enable: Autonomous agents, personal assistants, small-team tools where the LLM should be able to learn and update its own knowledge.

When to leave off: Agents serving many users where per-conversation self-writes would flood the agent's profile.

Troubleshooting

• "No user token found" — Run npx configure-mcp login and complete phone verification.
• Only seeing self tools — You skipped phone verification. Run npx configure-mcp login again.
• "Tool not connected" — Connect Gmail/Calendar/etc at configure.dev. Use configure_get_profile to check connection status.
• "Permission denied" — User profile writes are restricted to /agents/{your-agent}/.
• Token expired — Tokens last 30 days. Run npx configure-mcp login to re-authenticate.

---

For programmatic access beyond MCP, see the SDK Reference.