CLEAR TANGLEUNTANGLE YOUR THINKING

MCP Server

Connect to AI assistants via Model Context Protocol

The Clear Tangle MCP Server lets Claude, ChatGPT, and supported local clients work with your Clear Tangle account. Hosted connections use secure OAuth, keep access tied to the signed-in user, and send sensitive actions back to Clear Tangle for approval.

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants to use external tools and data sources. Clear Tangle supports hosted assistant connections as well as a local MCP package for compatible clients.

Supported Platforms

Claude

Hosted OAuth connection (Beta)

ChatGPT

Hosted OAuth connection (Beta)

Cursor

Local MCP package

Kiro

Local MCP package

Connect Claude or ChatGPT

Hosted connections require no local installation. Clear Tangle shows the connection values and platform-specific instructions inside your account.

  1. 1Open Clear Tangle Settings → Integrations → AI Assistants.
  2. 2Choose Claude or ChatGPT and open its setup guide.
  3. 3Copy the MCP server URL and the platform’s public OAuth Client ID.
  4. 4Add Clear Tangle in the assistant using the exact settings shown in the guide. Do not enter a client secret.
  5. 5Sign in to Clear Tangle, review the identity and tool-access disclosures, then allow tool access.
  6. 6Verify the connection by asking the assistant to search your Clear Tangle account.
Open AI Assistant Connections

Hosted connection safeguards

Read requests can use your current account data after connection. Actions that change data, send externally, publish, archive, automate work, or use AI credits create a pending approval in Clear Tangle. Delete tools are never available through hosted assistant connections.

If a connection card says Admin setup required, your Clear Tangle administrator must finish the platform’s OAuth configuration before you can connect.

Local MCP Package

For Cursor, Kiro, Claude Desktop, and other compatible local clients, run the standalone package with npx:

Run with npxbash
npx clear-tangle-mcp

Or install globally:

Global installationbash
npm install -g clear-tangle-mcp

Local Client Configuration

Claude Desktop

Config file locations:

  • • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • • Linux: ~/.config/claude/claude_desktop_config.json
claude_desktop_config.jsonjson
{
  "mcpServers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "env": {
        "BACKEND_URL": "https://app.cleartangle.com/api",
        "LOGIN_URL": "https://app.cleartangle.com/login"
      }
    }
  }
}

Cursor

Config: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/settings.json

Same JSON format as Claude Desktop.

Kiro

Config: ~/.kiro/mcp-servers.json

mcp-servers.jsonjson
{
  "servers": {
    "clear-tangle": {
      "command": "npx",
      "args": ["-y", "clear-tangle-mcp"],
      "environment": {
        "BACKEND_URL": "https://app.cleartangle.com/api",
        "LOGIN_URL": "https://app.cleartangle.com/login"
      }
    }
  }
}

Local Package Authentication

Hosted connections use OAuth instead

The four options below apply to the standalone local package. Claude and ChatGPT hosted connections use the OAuth flow shown in Clear Tangle’s AI Assistants tab.

Four ways to authenticate:

1. API Key (Recommended)

Best for automation

Create an API key in Settings > API Keys and add it to your config:

"env": {
  "CLEARTANGLE_API_KEY": "ctak_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "BACKEND_URL": "https://app.cleartangle.com/api"
}

API keys don’t expire and persist across restarts. Learn more about API keys

2. Browser Auth

Say “authenticate with Clear Tangle” to your AI assistant. A browser window opens, you log in, and the token is captured automatically.

3. Credential Auth

Set environment variables for auto-login:

"env": {
  "CLEARTANGLE_USERNAME": "your@email.com",
  "CLEARTANGLE_PASSWORD": "your-password"
}

4. Manual Token/Key

Say “set my Clear Tangle API key to [key]” or “set my Clear Tangle token to [token]” at runtime.

Token Storage

Credentials are stored locally at ~/.clear-tangle-mcp/token.json. JWT tokens expire after 24 hours; API keys persist indefinitely until revoked.

Local Package Tools (21)

Hosted connections use a broader protected tool set

Claude and ChatGPT hosted connections expose Clear Tangle’s current non-delete tool suite. Read tools run against your account; sensitive actions wait for approval in Clear Tangle.

Authentication (7)

authenticate

Browser-based OAuth login

login_with_credentials

Email/password login

set_api_key

Set API key (recommended)

set_token

Manually set JWT token

check_auth

Check auth status

test_connection

Diagnose connectivity

logout

Clear credentials

Tasks (7)

list_tasks

List with filters

get_task

Get task details

create_task

Create new task

update_task

Update task

complete_task

Mark complete

delete_task

Delete task (local package only)

get_tasks_dashboard

Dashboard view

Thoughts (5)

list_thoughts

List captures

get_thought

Get capture details

capture_thought

Create capture

update_thought

Update capture

delete_thought

Delete capture (local package only)

Plans (2)

get_plan

Get current plan

generate_plan

Generate new plan

Example Conversations

Search my Clear Tangle for the latest project decision
Create a task called "Review PR #123" with high priority
Show me my tasks for today
Capture this thought: "Remember to update the documentation"
Generate a priority plan for the week
What tasks are overdue?
Mark task xyz-123 as completed

Security Best Practices

  • Use the hosted OAuth connection for Claude and ChatGPT
  • Review pending changes and external actions before approving them in Clear Tangle
  • Never enter or share a client secret for the hosted public OAuth clients
  • For the local package, store credentials in a secure environment manager rather than a config file
  • Set local token-file permissions to chmod 600 ~/.clear-tangle-mcp/token.json
  • Keep local MCP configuration files out of version control

Local Package Environment Variables

VariableDefaultDescription
CLEARTANGLE_API_KEY(none)API key (recommended)
BACKEND_URLhttps://app.cleartangle.com/apiAPI base URL
LOGIN_URLhttps://app.cleartangle.com/loginLogin page URL
CLEARTANGLE_USERNAME(none)Auto-login email
CLEARTANGLE_PASSWORD(none)Auto-login password

Related Documentation

API Keys GuideAPI ReferenceSlack Integration