MCP Interface

Hoard implements the Model Context Protocol (MCP) to expose tools to AI agents.

What is MCP?

MCP (Model Context Protocol) is a standard for AI agents to interact with external tools and data sources. It defines:

Transport — How messages are sent (HTTP, stdio)
Protocol — JSON-RPC 2.0
Tools — Functions agents can call
Resources — Data agents can access

Hoard’s MCP Server

Hoard runs an HTTP MCP server:

hoard serve

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "meeting notes",
      "limit": 10
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [...],
    "next_cursor": "20"
  }
}

The result field contains the tool response directly (not wrapped in a content array).

Available Tools

Tool	Scope	Description
`search`	`search`	Hybrid search, chunks grouped by entity
`get`	`get`	Full entity with all chunks
`get_chunk`	`get`	Single chunk with context
`memory_get`	`memory.read`	Get stored context
`memory_put`	`memory.write`	Store context
`memory_search`	`memory.read`	Search memory
`sync`	`sync`	Run sync with lock
`sync_status`	`sync`	Health and status
`sync_run`	`sync`	Run sync without lock
`inbox_put`	`ingest`	Write to agent inbox
`agent.*`	varies	Agent registration and management (Orchestrator)
`task.*`	varies	Task lifecycle tools (Orchestrator)
`artifact.*`	varies	Task artifacts (Orchestrator)
`event.*`	varies	Events (Orchestrator)
`cost.*`	varies	Cost tracking (Orchestrator)
`workflow.*`	varies	Workflows (Orchestrator)

Tools NOT Exposed

For security, these tools are never exposed via MCP:

Tool	Reason
`export_all`	Would enable bulk exfiltration
`list_all`	Would enable enumeration
`query(sql)`	Would bypass security

Tool Schemas

search

{
  "name": "search",
  "description": "Search indexed content with hybrid search",
  "inputSchema": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "limit": {
        "type": "integer",
        "default": 20,
        "description": "Maximum results"
      },
      "source": {
        "type": "string",
        "description": "Filter by source (e.g., 'obsidian')"
      },
      "cursor": {
        "type": "string",
        "description": "Pagination cursor from previous response"
      },
      "types": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Result types (entity, memory)"
      },
      "include_memory": {
        "type": "boolean",
        "description": "Deprecated. Use types instead."
      }
    }
  }
}

get

{
  "name": "get",
  "description": "Get full entity content with all chunks",
  "inputSchema": {
    "type": "object",
    "required": ["entity_id"],
    "properties": {
      "entity_id": {
        "type": "string",
        "description": "Entity UUID"
      }
    }
  }
}

get_chunk

{
  "name": "get_chunk",
  "description": "Get single chunk with surrounding context",
  "inputSchema": {
    "type": "object",
    "required": ["chunk_id"],
    "properties": {
      "chunk_id": {
        "type": "string",
        "description": "Chunk ID (format: entity_id:index)"
      },
      "context_chunks": {
        "type": "integer",
        "default": 0,
        "maximum": 10,
        "description": "Include N chunks before/after (0-10)"
      }
    }
  }
}

memory_get

{
  "name": "memory_get",
  "description": "Retrieve stored context by key or id",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Memory id"
      },
      "key": {
        "type": "string",
        "description": "Memory key"
      }
    }
  }
}

memory_put

{
  "name": "memory_put",
  "description": "Store context for later retrieval",
  "inputSchema": {
    "type": "object",
    "required": ["key", "content"],
    "properties": {
      "key": {
        "type": "string",
        "description": "Memory key"
      },
      "content": {
        "type": "string",
        "description": "Content to store"
      },
      "tags": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Optional tags for categorization"
      },
      "metadata": {
        "type": "object",
        "description": "Optional metadata"
      },
      "ttl_days": {
        "type": "integer",
        "description": "Optional TTL in days"
      },
      "expires_at": {
        "type": "string",
        "description": "Optional ISO timestamp"
      }
    }
  }
}

inbox_put

{
  "name": "inbox_put",
  "description": "Write content into the agent inbox",
  "inputSchema": {
    "type": "object",
    "required": ["content"],
    "properties": {
      "content": {"type": "string"},
      "title": {"type": "string"},
      "tags": {"type": "array", "items": {"type": "string"}},
      "metadata": {"type": "object"},
      "filename": {"type": "string"},
      "extension": {"type": "string"},
      "sync_immediately": {"type": "boolean"}
    }
  }
}

Authentication

All requests require Bearer token authentication:

Authorization: Bearer hoard_sk_544e528b4b1ae6...

The token must:

Exist in Hoard configuration
Have required scope for the tool

Transport Options

HTTP (Default)

hoard serve

URL: http://127.0.0.1:19850/mcp
Protocol: JSON-RPC 2.0 over HTTP POST
Auth: Bearer token in header

Stdio (Alternative)

hoard mcp stdio

For MCP clients that require stdio transport.

Using with AI Agents

Claude Code

{
  "mcpServers": {
    "hoard": {
      "url": "http://127.0.0.1:19850/mcp",
      "headers": {
        "Authorization": "Bearer hoard_sk_..."
      }
    }
  }
}