Agent Workflows

End-to-end examples showing how AI agents chain MCP tools together, plus REST API usage for application integration.

MCP Tool Examples

These examples show read operations (search, sql, describe, graph) and write operations (create_table, add_rows, add_documents, drop_table) available via MCP tools.

Investigation: Search → SQL → Graph

Scenario: an agent needs to understand who's working on authentication issues and what's connected.

Step 1 — Search for context

The agent searches across all synced content for relevant documents:

{
  "tool": "search",
  "params": {
    "query": "authentication JWT",
    "limit": 5
  }
}

Returns matching documents from Notion and Zulip with highlighted snippets and source attribution.

Step 2 — Query structured data

Now the agent queries the task database for specifics:

{
  "tool": "sql",
  "params": {
    "query": "SELECT name, status, priority, assignee FROM project_tasks WHERE name LIKE '%JWT%' OR name LIKE '%auth%'"
  }
}

Returns a table of matching tasks with their assignees, statuses, and priorities.

Step 3 — Explore relationships

The agent follows the assignee to see everything connected to them:

{
  "tool": "graph",
  "params": {
    "table": "team_members",
    "key": "Alice Chen",
    "operation": "neighbors",
    "depth": 2,
    "direction": "reverse"
  }
}

Returns all entities connected to Alice—her assigned tasks, incidents she reported, and further connections.

Discovery: Describe → SQL

Scenario: the agent doesn't know what data is available and needs to explore.

Step 1 — Discover the schema

{
  "tool": "describe",
  "params": {}
}

Returns all available tables, their columns and types, and registered foreign-key relationships. The agent now knows what to query.

Step 2 — Query based on discovered tables

{
  "tool": "sql",
  "params": {
    "query": "SELECT team, COUNT(*) as member_count FROM team_members GROUP BY team ORDER BY member_count DESC"
  }
}

Path Finding

Scenario: find the connection between a person and an incident.

{
  "tool": "graph",
  "params": {
    "table": "team_members",
    "key": "Alice Chen",
    "operation": "path",
    "to_table": "incidents",
    "to_key": "API Gateway Timeout",
    "depth": 4
  }
}

Returns the shortest path of relationships linking Alice Chen to the "API Gateway Timeout" incident—through task assignments, team membership, or incident reports.

REST API Examples

When running with --port, Teidelum exposes a REST API for application integration. These examples use curl but any HTTP client works.

Creating and querying data

# Start the server
teidelum --port 8080

# Create a table
curl -X POST http://localhost:8080/api/v1/tables \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customers",
    "source": "crm",
    "columns": [
      {"name": "id", "type": "int"},
      {"name": "name", "type": "varchar"},
      {"name": "email", "type": "varchar"}
    ],
    "rows": [
      [1, "Alice", "alice@example.com"],
      [2, "Bob", "bob@example.com"]
    ]
  }'

# Insert more rows
curl -X POST http://localhost:8080/api/v1/tables/customers/rows \
  -H "Content-Type: application/json" \
  -d '{"rows": [[3, "Charlie", "charlie@example.com"]]}'

# Query with SQL
curl -X POST http://localhost:8080/api/v1/sql \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM customers WHERE id > 1"}'

Adding search documents

curl -X POST http://localhost:8080/api/v1/documents \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "id": "doc-001",
      "source": "wiki",
      "title": "Onboarding Guide",
      "body": "Welcome to the team. Here is how to get started..."
    }]
  }'

# Search
curl -X POST http://localhost:8080/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "onboarding", "limit": 5}'

With authentication

Set the TEIDELUM_API_KEY environment variable to require a Bearer token on every request:

TEIDELUM_API_KEY=secret teidelum --port 8080

curl -X POST http://localhost:8080/api/v1/tables \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "secure_table", "source": "app", "columns": [{"name": "id", "type": "int"}], "rows": []}'