API & MCP Server

ThoughtFree provides a public REST API and an MCP (Model Context Protocol) server for integrating with AI assistants and external tools.

Public API

API Keys

Generate API keys in Settings > API Keys:

1. Click Create API key and give it a name
2. Copy the key immediately — it’s only shown once
3. You can have up to 5 active keys
4. Each key shows its creation date and last-used timestamp

Keys can be revoked at any time from the same settings page.

Authentication

All API requests use Bearer token authentication:

curl https://app.thoughtfree.io/api/v1/thoughts \
  -H "Authorization: Bearer tf_YOUR_API_KEY"

Endpoints

Method	Endpoint	Description
GET	/api/v1/thoughts	List thoughts with pagination
POST	/api/v1/thoughts	Create a new thought
GET	/api/v1/thoughts/:id	Get a specific thought
PATCH	/api/v1/thoughts/:id	Update a thought
DELETE	/api/v1/thoughts/:id	Soft-delete a thought
POST	/api/v1/thoughts/:id/restore	Restore a deleted thought
GET	/api/v1/categories	List all categories
GET	/api/v1/stats	Usage statistics
POST	/api/v1/search	Full-text search
POST	/api/v1/brain	Semantic/vector search (Pro)

---

MCP Server (Claude Desktop, VS Code, Cursor)

The MCP server lets AI assistants like Claude read and write your thoughts directly. There are two ways to connect.

Option 1: Remote Connector (Easiest)

No installation needed — connect directly through OAuth:

1. In your AI tool, add a custom MCP connector
2. Use the URL: https://app.thoughtfree.io/api/mcp
3. Sign in with your ThoughtFree account when prompted

Works with Claude Desktop and claude.ai.

Option 2: Local MCP Server

For Cursor, VS Code, or custom setups:

1. Generate an API key in Settings > API Keys
2. Add the following to your MCP configuration:

{
  "mcpServers": {
    "thoughtfree": {
      "command": "npx",
      "args": ["-y", "@thoughtfree/mcp-server"],
      "env": {
        "THOUGHTFREE_API_KEY": "tf_YOUR_API_KEY"
      }
    }
  }
}

The config file location depends on your tool:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: .cursor/mcp.json in your project
• VS Code: .vscode/mcp.json in your project

MCP Capabilities

Tools (what AI can do):

• Search, create, list, update, and delete thoughts
• Semantic search across your thought library
• List categories and get usage stats

Resources (what AI can read):

• thoughtfree://recent — your recent thoughts
• thoughtfree://starred — your starred thoughts
• thoughtfree://category/{key} — thoughts by category

Example Prompts for Claude

Once connected, try asking Claude:

• “What did I capture this week?”
• “Create a thought about the meeting notes from today”
• “Search my thoughts for anything about project deadlines”
• “Summarize my starred thoughts”