Claude MCP + HatiData: 24 Agent Tools

The Complete MCP Tool Reference

HatiData's MCP server exposes 24 tools that give Claude (and any MCP-compatible model) full access to agent-native data infrastructure. These tools cover five categories: memory management, chain-of-thought logging, semantic triggers, branch isolation, and query governance.

This guide catalogs every tool with its purpose, parameters, and practical usage. Configure your MCP client once, and all 24 tools are available immediately.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "hatidata": {
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "hatidata": {
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

Claude Code

Add to .claude/mcp.json in your project root:

{
  "mcpServers": {
    "hatidata": {
      "type": "sse",
      "url": "http://localhost:5440/mcp/sse",
      "headers": {
        "Authorization": "Bearer hd_live_your_api_key_here"
      }
    }
  }
}

After configuration, restart your client. The 24 tools will appear in the available tools list automatically.

Category 1: Memory Tools (5 tools)

Memory tools manage the agent's persistent knowledge store — storing, searching, retrieving, managing state, and deleting memories.

store_memory

Stores a new memory entry with automatic embedding generation.

Parameters:

• namespace (string, required) — Logical grouping for the memory
• content (string, required) — The information to store
• metadata (object, optional) — Key-value pairs for structured filtering

Returns: memory_id (UUID), namespace, created_at

When to use: When you learn something important that should be remembered across sessions — user preferences, discovered facts, task outcomes, configuration decisions.

search_memory

Searches memories using hybrid SQL + vector retrieval.

Parameters:

• query (string, required) — Natural language search query
• namespace (string, optional) — Filter to a specific namespace
• limit (integer, optional, default 10) — Maximum results to return
• min_similarity (float, optional, default 0.6) — Minimum cosine similarity threshold

Returns: Array of memories with memory_id, content, metadata, similarity, created_at

When to use: Before starting a task, to find relevant past knowledge. When a user asks about something you may have discussed before. When you need context from previous sessions.

get_agent_state

Retrieves a persistent key-value state entry.

Parameters:

• key (string, required) — The state key to retrieve

Returns: The stored value (any JSON type) or null if not set

When to use: For structured state like workflow progress, configuration settings, or counters that need to persist across sessions.

set_agent_state

Stores or updates a persistent key-value state entry.

Parameters:

• key (string, required) — The state key
• value (any JSON, required) — The value to store

Returns: Confirmation with the key and timestamp

When to use: To save workflow checkpoints, update counters, or store configuration that the agent needs to retrieve later.

delete_memory

Permanently removes a specific memory by ID.

Parameters:

• memory_id (string, required) — The UUID of the memory to delete

Returns: Confirmation of deletion

When to use: When a memory is outdated, incorrect, or needs to be removed for privacy reasons (e.g., GDPR right to erasure).

Category 2: Chain-of-Thought Tools (3 tools)

CoT tools record and replay the agent's reasoning process in an immutable, hash-chained ledger.

log_reasoning_step

Appends a new step to the current session's reasoning chain.

Parameters:

• session_id (string, required) — The reasoning session identifier
• step_type (string, required) — One of: observation, hypothesis, decision, action, reflection, error, planning, evaluation, tool_call, tool_result, memory_recall, context_switch
• content (string, required) — The reasoning content for this step
• confidence (float, optional) — Confidence score between 0 and 1
• metadata (object, optional) — Additional context for the step

Returns: step_number, hash (cryptographic hash), session_id

When to use: When making important decisions that should be auditable. When working through complex reasoning that needs to be traceable. When compliance requires documentation of the decision-making process.

replay_decision

Retrieves the complete reasoning chain for a session.

Parameters:

• session_id (string, required) — The session to replay

Returns: Array of steps with step_number, step_type, content, hash, previous_hash, timestamp, plus chain validity status

When to use: To review past reasoning, debug unexpected decisions, or provide evidence for compliance audits.

get_session_history

Lists all reasoning sessions for the current agent.

Parameters:

• limit (integer, optional, default 20) — Maximum sessions to return
• offset (integer, optional, default 0) — Pagination offset

Returns: Array of sessions with session_id, step_count, first_step_at, last_step_at, chain_valid

When to use: To find past reasoning sessions by date or to get an overview of the agent's reasoning history.

Category 3: Semantic Trigger Tools (4 tools)

Trigger tools enable event-driven intelligence — registering interest in concepts and receiving notifications when relevant content appears.

register_trigger

Creates a new semantic trigger.

Parameters:

• concept (string, required) — Natural language description of what to watch for
• threshold (float, optional, default 0.75) — Minimum similarity for activation
• cooldown_seconds (integer, optional, default 60) — Minimum time between fires
• action (object, required) — Dispatch action: webhook, agent_notify, write_event, or flag_for_review

Returns: trigger_id, concept, threshold, created_at

When to use: When you need to monitor for specific types of events, content patterns, or conceptual matches without continuously polling.

list_triggers

Returns all active triggers for the current organization.

Parameters: None required

Returns: Array of triggers with all configuration details

delete_trigger

Removes a trigger by ID.

Parameters:

• trigger_id (string, required) — The trigger to delete

Returns: Confirmation of deletion

test_trigger

Evaluates test content against all triggers without firing actions.

Parameters:

• content (string, required) — The content to test against triggers

Returns: Array of matching triggers with similarity, would_fire, cooldown_active

When to use: To test and tune trigger thresholds without causing side effects.

Category 4: Branch Isolation Tools (5 tools)

Branch tools create isolated environments for safe data exploration and what-if analysis.

branch_create

Creates a new isolated branch with zero-copy views.

Parameters:

• description (string, optional) — Human-readable description of the branch purpose

Returns: branch_id, schema, tables (count), created_at

branch_query

Executes a SQL query within a branch's isolated environment.

Parameters:

• branch_id (string, required) — The branch to query within
• sql (string, required) — The SQL query to execute

Returns: Query results scoped to the branch

branch_merge

Merges branch changes back into the main schema.

Parameters:

• branch_id (string, required) — The branch to merge
• strategy (string, required) — One of: branch_wins, main_wins, manual, abort

Returns: Merge result with conflict details (if any)

branch_discard

Discards a branch and cleans up resources.

Parameters:

• branch_id (string, required) — The branch to discard

Returns: Confirmation of cleanup

branch_list

Lists all active branches.

Parameters: None required

Returns: Array of branches with branch_id, description, created_at, tables_materialized, last_accessed

Category 5: Query and Governance Tools (7 tools)

Query tools handle direct data access, schema inspection, and governance operations.

query

Executes a SQL query against the agent's data warehouse.

Parameters:

• sql (string, required) — The SQL query to execute

Returns: Result rows as structured JSON

When to use: For any structured data retrieval, aggregation, or analysis. Supports HatiData's semantic SQL functions (semantic_match, semantic_rank) for hybrid queries.

list_tables

Returns all accessible tables with metadata.

Parameters: None required

Returns: Array of tables with name, row_count, columns (summary)

describe_table

Returns the full schema for a specific table.

Parameters:

• table_name (string, required) — The table to describe

Returns: Column definitions with name, type, nullable, sample values

context_search

Performs semantic search across table descriptions and column names.

Parameters:

• query (string, required) — What kind of data to search for

Returns: Matching tables and columns ranked by relevance

When to use: When you know what kind of data you need but not which table contains it.

explain_query

Returns the execution plan for a query without running it.

Parameters:

• sql (string, required) — The query to explain

Returns: Query plan with estimated costs

get_quota

Returns current resource usage and remaining quota.

Parameters: None required

Returns: monthly_limit, used, remaining, reset_date

rotate_key

Generates a new API key and starts the grace period for the old one.

Parameters: None required

Returns: New API key (shown once), key_id, grace_period_ends

Practical Workflow Example

Here is how the 24 tools work together in a realistic agent workflow:

1. 1search_memory — Check for relevant past knowledge on the current task
2. 2list_tables + context_search — Discover relevant data sources
3. 3branch_create — Create an isolated environment for exploration
4. 4log_reasoning_step (observation) — Record initial findings
5. 5branch_query — Run exploratory queries in the safe branch
6. 6log_reasoning_step (hypothesis) — Form a hypothesis based on data
7. 7query — Validate against main data
8. 8log_reasoning_step (decision) — Record the decision and rationale
9. 9branch_merge or branch_discard — Merge good results or discard dead ends
10. 10store_memory — Save key findings for future reference
11. 11register_trigger — Set up monitoring for related future events

This workflow uses tools from all five categories, demonstrating how they compose into a complete agent operating loop.

Next Steps

With all 24 tools configured, Claude can manage its own persistent memory, log auditable reasoning, monitor for semantic events, explore data safely in branches, and query the warehouse directly. For framework-specific integrations that wrap these tools in Python classes, see the LangChain, CrewAI, and OpenAI Agents SDK guides.