Skip to main content

Quick Start

Connect to Lovelace and complete your first MCP workflow

This guide walks through the public Lovelace MCP gateway from authentication to a full agent workflow.

Prerequisites

  • A Lovelace account
  • An MCP-compatible client such as Claude Desktop, Claude Code, Cursor, or Windsurf
  • A client that supports MCP Streamable HTTP and the MCP HTTP authorization flow, or a client where you can manually complete OAuth configuration

Step 1: Configure Your Client

Use the public gateway endpoint:

  • URL: https://mcp.uselovelace.com/mcp
  • Transport: Streamable HTTP
  • Authorization: Let the client follow the gateway’s 401 challenge and Protected Resource Metadata discovery flow

Claude Desktop

json
{
  "mcpServers": {
    "lovelace": {
      "type": "streamable-http",
      "url": "https://mcp.uselovelace.com/mcp"
    }
  }
}

Claude Code

bash
claude mcp add lovelace --transport streamable-http \
  --url https://mcp.uselovelace.com/mcp

For other clients, see Client Setup.

Step 2: Let the Client Authorize

On first connection, the gateway challenges the client and points it to:

  • https://mcp.uselovelace.com/.well-known/oauth-protected-resource

From there, the client discovers Lovelace Accounts as the authorization server, completes OAuth 2.1 authorization, and starts sending bearer tokens on MCP requests.

If your client needs manual OAuth setup rather than automatic discovery, use the metadata discovered from the protected resource and configure the client to request the MCP endpoint as the resource/audience.

Step 3: Verify Access

Ask your client:

text
List my Lovelace workspaces

That should invoke lovelace_list_workspaces and return the workspaces you can access.

Step 4: Launch an Agent

Pick a workspace ID from the previous step, then ask your client to spawn an agent in that workspace:

text
Spawn a Lovelace agent in workspace ws_abc123 with agent type general to review our API performance bottlenecks

The underlying MCP tool is:

json
{
  "workspaceId": "ws_abc123",
  "agentType": "general",
  "task": "Review our API performance bottlenecks"
}

The gateway returns an agentId and initial status.

Step 5: Check Status and Results

Use the returned agentId to monitor progress:

text
Check the status of Lovelace agent agent_123

Then fetch the final result:

text
Get the result for Lovelace agent agent_123

The agent workflow uses:

  • lovelace_get_agent_status with agentId
  • lovelace_get_agent_result with agentId

Step 6: Read Matching Resources

You can also read the corresponding MCP resources directly:

  • lovelace://workspaces
  • lovelace://workspaces/ws_abc123
  • lovelace://agents/agent_123/status
  • lovelace://agents/agent_123/output

For knowledge documents discovered through search:

  • lovelace://knowledge/doc_456

What’s Next