Skip to main content

Resources Reference

Read Lovelace platform data through lovelace:// URIs

The public MCP gateway exposes read-only MCP resources alongside its tools.

Workspace Resources

lovelace://workspaces

Returns the list of workspaces accessible to the authenticated user.

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

lovelace://workspaces/{workspaceId}

Returns a specific workspace.

Example: lovelace://workspaces/ws_abc123

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 Resources

lovelace://agents

This is a discovery placeholder resource. Use lovelace_list_agents to discover agent IDs, then read the concrete status/output URIs below.

lovelace://agents/{agentId}/status

Returns the current status for an agent.

Example: lovelace://agents/agent_123/status

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://agents/{agentId}/output

Returns the result payload for an agent.

Example: lovelace://agents/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
}

Code Resources

lovelace://workspaces/{workspaceId}/code

Returns bounded metadata for source files visible in the workspace associated with the authenticated MCP session.

Example: lovelace://workspaces/ws_abc123/code

json
{
  "workspaceId": "ws_abc123",
  "files": [
    {
      "path": "src/index.ts",
      "name": "index.ts",
      "mimeType": "application/typescript",
      "language": "typescript",
      "sizeBytes": 2048,
      "updatedAt": "2025-02-01T14:30:00.000Z",
      "uri": "lovelace://workspaces/ws_abc123/code/src/index.ts"
    }
  ],
  "total": 1,
  "hasMore": false,
  "searchUriTemplate": "lovelace://workspaces/ws_abc123/code/search?query={query}",
  "limits": {
    "listLimit": 500,
    "searchLimit": 50
  }
}

lovelace://workspaces/{workspaceId}/code/{path}

Returns the text for a workspace-relative source file path.

Example: lovelace://workspaces/ws_abc123/code/src/index.ts

typescript
export const value = 1;

Code resource paths must be workspace-relative. Absolute paths, empty path segments, . and .. traversal, unsupported text encodings, oversized files, and unauthorized workspace access are rejected.

lovelace://workspaces/{workspaceId}/code/search?query={query}

Returns bounded code-search matches with snippets and file metadata.

Example: lovelace://workspaces/ws_abc123/code/search?query=createClient

json
{
  "workspaceId": "ws_abc123",
  "query": "createClient",
  "results": [
    {
      "file": {
        "path": "src/client.ts",
        "name": "client.ts",
        "mimeType": "application/typescript",
        "language": "typescript",
        "uri": "lovelace://workspaces/ws_abc123/code/src/client.ts"
      },
      "snippet": "export function createClient(config: ClientConfig) {",
      "line": 12
    }
  ],
  "total": 1,
  "limits": {
    "searchLimit": 50
  }
}

Media Resources

lovelace://workspaces/{workspaceId}/media

Returns bounded metadata for media assets visible in the workspace associated with the authenticated MCP session.

Example: lovelace://workspaces/ws_abc123/media

json
{
  "workspaceId": "ws_abc123",
  "media": [
    {
      "mediaId": "media_architecture_diagram",
      "name": "Architecture Diagram",
      "description": "System topology diagram",
      "kind": "image",
      "mimeType": "image/png",
      "sizeBytes": 4096,
      "width": 1024,
      "height": 768,
      "updatedAt": "2025-02-01T14:30:00.000Z",
      "uri": "lovelace://workspaces/ws_abc123/media/media_architecture_diagram"
    }
  ],
  "total": 1,
  "hasMore": false,
  "searchUriTemplate": "lovelace://workspaces/ws_abc123/media/search?query={query}",
  "limits": {
    "listLimit": 250,
    "searchLimit": 50
  }
}

lovelace://workspaces/{workspaceId}/media/{mediaId}

Returns a media payload by stable media identifier. Binary media is returned as a string with explicit encoding.

Example: lovelace://workspaces/ws_abc123/media/media_architecture_diagram

json
{
  "mediaId": "media_architecture_diagram",
  "name": "Architecture Diagram",
  "kind": "image",
  "mimeType": "image/png",
  "sizeBytes": 4096,
  "width": 1024,
  "height": 768,
  "updatedAt": "2025-02-01T14:30:00.000Z",
  "encoding": "base64",
  "data": "iVBORw0KGgo="
}

Media reads are resolved by the gateway's backing media service. Unsupported content, oversized payloads, missing assets, and unauthorized workspace access are rejected.

lovelace://workspaces/{workspaceId}/media/search?query={query}

Returns bounded search matches across the workspace's media assets.

Example: lovelace://workspaces/ws_abc123/media/search?query=diagram

json
{
  "workspaceId": "ws_abc123",
  "query": "diagram",
  "results": [
    {
      "media": {
        "mediaId": "media_architecture_diagram",
        "name": "Architecture Diagram",
        "kind": "image",
        "mimeType": "image/png",
        "uri": "lovelace://workspaces/ws_abc123/media/media_architecture_diagram"
      },
      "snippet": "System topology diagram"
    }
  ],
  "total": 1,
  "limits": {
    "searchLimit": 50
  }
}

Knowledge Resources

lovelace://knowledge

This is a discovery placeholder resource. Use lovelace_search_knowledge to find relevant documents, then read a specific document URI.

lovelace://knowledge/{documentId}

Returns a stored knowledge document.

Example: lovelace://knowledge/doc_456

json
{
  "id": "doc_456",
  "title": "Authentication Architecture",
  "content": "# Authentication Architecture\n\nOur authentication system...",
  "mimeType": "text/markdown",
  "workspaceId": "ws_abc123",
  "metadata": {
    "source": "engineering-handbook"
  },
  "createdAt": "2025-01-20T09:00:00.000Z",
  "updatedAt": "2025-01-25T15:00:00.000Z"
}

External Asset Resources

lovelace://workspaces/{workspaceId}/external-assets

Returns bounded metadata for external assets explicitly referenced by the workspace and approved by the backing external asset service.

Example: lovelace://workspaces/ws_abc123/external-assets

json
{
  "workspaceId": "ws_abc123",
  "assets": [
    {
      "assetId": "asset_api_docs",
      "name": "API Docs",
      "description": "Allowlisted API documentation",
      "kind": "web_page",
      "externalUri": "https://docs.example.com/api",
      "mimeType": "text/html",
      "sizeBytes": 1234,
      "fetchedAt": "2025-02-01T14:30:00.000Z",
      "cache": {
        "hit": true,
        "cachedAt": "2025-02-01T14:30:00.000Z",
        "expiresAt": "2025-02-01T14:35:00.000Z"
      },
      "uri": "lovelace://workspaces/ws_abc123/external-assets/asset_api_docs"
    }
  ],
  "total": 1,
  "hasMore": false,
  "searchUriTemplate": "lovelace://workspaces/ws_abc123/external-assets/search?query={query}",
  "limits": {
    "listLimit": 250,
    "searchLimit": 50
  }
}

lovelace://workspaces/{workspaceId}/external-assets/{assetId}

Returns text for an allowlisted external asset by stable asset identifier.

Example: lovelace://workspaces/ws_abc123/external-assets/asset_api_docs

html
<h1>API Docs</h1>

External asset reads are resolved by the gateway's backing asset service. Clients cannot pass arbitrary URLs through the resource URI; assets must already be referenced by the workspace and approved by policy. Non-allowlisted assets, rate-limited fetches, unsupported content, oversized responses, missing assets, and unauthorized workspace access are rejected.

lovelace://workspaces/{workspaceId}/external-assets/search?query={query}

Returns bounded search matches across the workspace's allowlisted external assets.

Example: lovelace://workspaces/ws_abc123/external-assets/search?query=oauth

json
{
  "workspaceId": "ws_abc123",
  "query": "oauth",
  "results": [
    {
      "asset": {
        "assetId": "asset_api_docs",
        "name": "API Docs",
        "kind": "web_page",
        "externalUri": "https://docs.example.com/api",
        "mimeType": "text/html",
        "uri": "lovelace://workspaces/ws_abc123/external-assets/asset_api_docs"
      },
      "snippet": "OAuth authorization endpoint"
    }
  ],
  "total": 1,
  "limits": {
    "searchLimit": 50
  }
}

Usage Notes

  • Workspace resources are listed directly by the gateway
  • Code resources are listed for the authenticated session workspace
  • Media resources are listed for the authenticated session workspace
  • External asset resources are listed for the authenticated session workspace
  • Agent and knowledge resources are discovered dynamically through tools
  • The public launch docs do not promise resource subscription behavior for the public gateway