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:reador equivalentmcp: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:reador equivalentmcp: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:reador equivalentmcp: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:writeor equivalentmcp: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:reador equivalentmcp: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:reador equivalentmcp: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:reador equivalentmcp: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:writeor equivalentmcp: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.