Building with MCP

Thogits exposes a Model Context Protocol (MCP) server that lets AI assistants create tags, manage thogits, run filters, and more — all through natural language. This guide covers connecting Claude and custom MCP clients to your Thogits instance.

Connecting Claude Code

Add Thogits to your project’s .mcp.json file:

{
  "mcpServers": {
    "thogits": {
      "type": "sse",
      "url": "https://app.thogits.com/api/mcp/sse"
    }
  }
}

Claude Code will automatically discover the available tools on startup. You can then ask Claude to interact with your Thogits instance conversationally — “create a Task tag with status and priority fields”, “show me all overdue tasks”, etc.

Connecting Claude Desktop

Add the same configuration in Claude Desktop’s settings (Settings > Developer > MCP Servers):

{
  "mcpServers": {
    "thogits": {
      "type": "sse",
      "url": "https://app.thogits.com/api/mcp/sse"
    }
  }
}

After saving, restart Claude Desktop. The Thogits tools will appear in the tools menu.

Tip

The MCP endpoint at https://app.thogits.com/api/mcp/sse requires an authenticated session. Log in via the web app first to establish a session cookie.

Available tools

Thogits exposes these MCP tools:

Schema management

add_tag, get_tag, edit_tag, delete_tag, get_tags

Thogit CRUD

add_thogit, edit_thogit, delete_thogit, get_thogit, get_thogits

Tag operations

apply_tag_to_thogit, update_tag_field_values, remove_tag_from_thogit

Bulk operations

bulk_add_thogits, bulk_delete_thogits, bulk_apply_tag, bulk_remove_tag, bulk_update_field_values

Query tools

validate_filter, explain_query, get_outdated_thogit_tags

Views

create_view, get_view, list_views, update_view, delete_view

Custom MCP client

If you are building your own MCP client, here is the connection protocol.

1. Open the SSE connection

   Connect to the SSE endpoint. The server sends an endpoint event with the URL for sending JSON-RPC requests.

   curl -N https://app.thogits.com/api/mcp/sse \
     -b cookies.txt -c cookies.txt

   The server responds with a stream. The first event contains the message endpoint:

   event: endpoint
   data: /api/mcp/message?session_id=SESSION_ID

   Save this URL — all JSON-RPC requests go to it.

2. Send the initialize request

   POST a JSON-RPC initialize request to the endpoint URL from step 1.

   curl -X POST "https://app.thogits.com/api/mcp/message?session_id=SESSION_ID" \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {"name": "my-client", "version": "1.0.0"}
       }
     }'

   The response (on the SSE stream) contains server capabilities and protocol version.

3. Discover available tools

   curl -X POST "https://app.thogits.com/api/mcp/message?session_id=SESSION_ID" \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list",
       "params": {}
     }'

   The response lists all tools with their names, descriptions, and input schemas.

4. Call a tool

   Execute a tool by sending a tools/call request with the tool name and arguments.

   curl -X POST "https://app.thogits.com/api/mcp/message?session_id=SESSION_ID" \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "jsonrpc": "2.0",
       "id": 3,
       "method": "tools/call",
       "params": {
         "name": "get_tags",
         "arguments": {}
       }
     }'

   Tool results arrive as SSE events on the open connection.

Example workflows

Create a project tracking system

This shows an AI assistant setting up a complete schema and populating it with data.

Prompt: “Create a project tracking system with Tasks, Projects, and People.”

The AI would call these tools in sequence:

1. get_tags                          # Check what tags already exist
2. add_tag (Person)                  # Create Person tag with department, role fields
3. add_tag (Project)                 # Create Project tag with name, lead (Reference), status
4. add_tag (Task)                    # Create Task tag with status, priority, assignee, project
5. bulk_add_thogits                  # Create initial people, projects, and tasks

The AI discovers existing schemas first, creates tags that do not exist yet, then populates data in bulk.

Find all overdue tasks

Prompt: “Show me all tasks that are past due and not done.”

1. get_tags                          # Discover Task tag schema to know field names
2. get_thogits                       # Filter with:
                                     #   {"and": [
                                     #     {"has_tag": "Task"},
                                     #     {"Task.due_date": {"lt": "2026-04-06"}},
                                     #     {"not": {"Task.status": {"match": "Done"}}}
                                     #   ]}

Bulk update status

Prompt: “Move all tasks in Sprint 12 to Done.”

1. get_tags                          # Confirm Task tag has status and sprint fields
2. get_thogits                       # Preview: find tasks in Sprint 12
                                     #   {"and": [
                                     #     {"has_tag": "Task"},
                                     #     {"Task.sprint": "SPRINT_12_ID"}
                                     #   ]}
3. bulk_update_field_values          # Update with dry_run: true first
                                     #   tag_name: "Task"
                                     #   filter: (same as above)
                                     #   field_values: {"status": {"variant": "Done"}}
                                     #   merge: true, dry_run: true
4. bulk_update_field_values          # Execute with dry_run: false

Tips for AI integration

Discover before creating

Always call get_tags before creating new tags. This prevents duplicate schemas and lets the AI understand what fields are already available.

Validate complex filters

Use validate_filter before running complex queries. It checks the filter syntax and field references without executing the query, returning clear error messages for any issues.

Preview bulk operations

All bulk operations (bulk_delete_thogits, bulk_apply_tag, bulk_remove_tag, bulk_update_field_values) support dry_run: true. This returns the thogits that would be affected without making changes. Always dry-run first to confirm the scope.

Debug filter issues

Use explain_query to get a human-readable explanation of what a filter does. This is useful when a filter returns unexpected results — the explanation shows how each condition is interpreted.

Use merge for partial updates

When calling bulk_update_field_values or update_tag_field_values, set merge: true to update only the specified fields. Without merge, omitted fields are set to null.