Attunement API & Agentic Ingress (MCP)

This specification covers programmatic integration, REST API interfaces, and Model Context Protocol (MCP) connectivity for autonomous agents.

---

1. Authentication

All programmatic requests to ToFF Attunement require an API Key supplied via the Authorization header:

Authorization: Bearer <YOUR_INSTITUTIONAL_API_KEY>

API keys can be generated within the KaraKeep web portal under Settings > API Tokens.

---

2. Core REST API Endpoints

Ingest New Asset

• Endpoint: POST /api/v1/bookmarks
• Content-Type: application/json

curl -X POST https://listen.tomoffinland.org/api/v1/bookmarks \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "link",
    "url": "https://www.artnews.com/art-news/news/tom-of-finland-foundation-exhibition",
    "title": "ARTnews: Tom of Finland Foundation Retrospective",
    "tags": ["press", "artnews"]
  }'

Query Assets

• Endpoint: GET /api/v1/bookmarks
• Query Parameters:
  • q: Search keyword or phrase
  • tags: Filter by specific tag
  • listId: Filter by specific workspace list
  • limit: Number of results (default: 20)

curl -G https://listen.tomoffinland.org/api/v1/bookmarks \
  -H "Authorization: Bearer $API_TOKEN" \
  --data-urlencode "q=Tom House" \
  --data-urlencode "limit=10"

---

3. Model Context Protocol (MCP) Integration

Autonomous AI agents (such as Antigravity, Claude Desktop, or Claude Code) can be connected directly to ToFF Attunement to provide contextual awareness of contemporary discourse:

{
  "mcpServers": {
    "toff-attunement": {
      "command": "npx",
      "args": ["-y", "karakeep-mcp"],
      "env": {
        "KARAKEEP_URL": "https://listen.tomoffinland.org",
        "KARAKEEP_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Available MCP Tools:

• search_attunement(query, limit): Search cultural discourse, notes, and OCR transcripts.
• ingest_record(url, tags, notes): Submit new external media or articles directly to the ingestion pipeline.
• get_record_details(recordId): Retrieve complete textual and visual metadata for a specific record.