Skip to main content

Tools Reference

Current tool contracts exposed by the MCP Gateway

All tools return JSON content through standard MCP tool responses.

Workspace Tools

lovelace_list_workspaces

List all workspaces accessible to the authenticated user.

  • Input: none
  • Required scopes: workspace:read or equivalent mcp:read / read

Output

json
{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "My Project",
      "description": "Main development workspace",
      "memberCount": 3,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "total": 1
}

lovelace_get_workspace

Get detailed information about a specific workspace.

  • Required scopes: workspace:read or equivalent mcp:read / read

Input

json
{
  "workspaceId": "ws_abc123"
}

Output

json
{
  "id": "ws_abc123",
  "name": "My Project",
  "description": "Main development workspace",
  "ownerId": "user_123",
  "memberCount": 3,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-02-01T14:30:00.000Z"
}

Agent Tools

lovelace_list_agents

List agents in a workspace.

  • Required scopes: agents:read or equivalent mcp:read / read

Input

json
{
  "workspaceId": "ws_abc123"
}

Output

json
{
  "agents": [
    {
      "id": "agent_123",
      "name": "API Review Agent",
      "description": "Performance review run",
      "type": "general",
      "task": "Review API bottlenecks",
      "status": "completed",
      "statusMessage": "Finished successfully",
      "workspaceId": "ws_abc123",
      "createdAt": "2025-02-17T12:00:00.000Z",
      "updatedAt": "2025-02-17T12:05:30.000Z"
    }
  ],
  "total": 1
}

lovelace_spawn_agent

Spawn an agent to execute a task in a workspace.

  • Required scopes: agents:write or equivalent mcp:write / write

Input

json
{
  "workspaceId": "ws_abc123",
  "agentType": "general",
  "task": "Review the authentication module for security issues",
  "config": {
    "priority": "high"
  }
}

Output

json
{
  "agentId": "agent_123",
  "status": "initializing",
  "message": "Agent spawned successfully. Use lovelace_get_agent_status with agentId \"agent_123\" to monitor progress."
}

lovelace_get_agent_status

Get the current execution status of an agent.

  • Required scopes: agents:read or equivalent mcp:read / read

Input

json
{
  "agentId": "agent_123"
}

Output

json
{
  "id": "agent_123",
  "name": "API Review Agent",
  "description": "Performance review run",
  "type": "general",
  "task": "Review API bottlenecks",
  "status": "completed",
  "statusMessage": "Finished successfully",
  "workspaceId": "ws_abc123",
  "createdAt": "2025-02-17T12:00:00.000Z",
  "updatedAt": "2025-02-17T12:05:30.000Z",
  "completedAt": "2025-02-17T12:05:30.000Z"
}

lovelace_get_agent_result

Get the output produced by an agent.

  • Required scopes: agents:read or equivalent mcp:read / read

Input

json
{
  "agentId": "agent_123"
}

Output

json
{
  "agentId": "agent_123",
  "status": "completed",
  "result": {
    "summary": "Found 3 bottlenecks in the authentication flow"
  },
  "artifacts": [
    {
      "id": "artifact_1",
      "name": "report.md",
      "mimeType": "text/markdown",
      "uri": "https://example.com/report.md"
    }
  ],
  "error": null
}

Knowledge Tools

lovelace_search_knowledge

Search knowledge in a workspace.

  • Required scopes: knowledge:read or equivalent mcp:read / read

Input

json
{
  "workspaceId": "ws_abc123",
  "query": "authentication best practices",
  "limit": 5
}

Output

json
{
  "results": [
    {
      "documentId": "doc_456",
      "title": "Authentication Architecture",
      "score": 0.95,
      "snippet": "Our authentication system uses OAuth 2.1 with PKCE...",
      "mimeType": "text/markdown",
      "resourceUri": "lovelace://knowledge/doc_456"
    }
  ],
  "total": 1,
  "query": "authentication best practices"
}

lovelace_store_knowledge

Store a knowledge document in a workspace.

  • Required scopes: knowledge:write or equivalent mcp:write / write

Input

json
{
  "workspaceId": "ws_abc123",
  "title": "API Rate Limiting Policy",
  "content": "# API Rate Limiting Policy\n\n...",
  "mimeType": "text/markdown",
  "metadata": {
    "source": "engineering-handbook"
  }
}

Output

json
{
  "documentId": "doc_456",
  "title": "API Rate Limiting Policy",
  "mimeType": "text/markdown",
  "resourceUri": "lovelace://knowledge/doc_456",
  "createdAt": "2025-02-17T12:00:00.000Z"
}

Putting it together

The tools compose naturally into a workflow. Here is a complete Python example that goes from picking a workspace to reading an agent's output:

python
import asyncio
import json
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

TOKEN = os.environ["LOVELACE_TOKEN"]

async def main():
    async with streamablehttp_client(
        "https://mcp.uselovelace.com/mcp",
        headers={"Authorization": f"Bearer {TOKEN}"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 1. List workspaces and pick one
            ws = json.loads(
                (await session.call_tool("lovelace_list_workspaces", {})).content[0].text
            )
            workspace_id = ws["workspaces"][0]["id"]

            # 2. Spawn an agent
            spawn = json.loads(
                (
                    await session.call_tool(
                        "lovelace_spawn_agent",
                        {
                            "workspaceId": workspace_id,
                            "agentType": "general",
                            "task": "Summarize the key security risks in a public API",
                        },
                    )
                ).content[0].text
            )
            agent_id = spawn["agentId"]

            # 3. Poll until done
            while True:
                status = json.loads(
                    (
                        await session.call_tool(
                            "lovelace_get_agent_status", {"agentId": agent_id}
                        )
                    ).content[0].text
                )["status"]
                if status in ("completed", "failed"):
                    break
                await asyncio.sleep(2)

            # 4. Read the result
            if status == "completed":
                output = json.loads(
                    (
                        await session.call_tool(
                            "lovelace_get_agent_result", {"agentId": agent_id}
                        )
                    ).content[0].text
                )
                print(output["result"])

asyncio.run(main())

For more patterns — including knowledge-augmented agents and parallel multi-workspace orchestration — see Agent Workflows.