Use Apps via OpenClaw

Learn how to let users use your app via OpenClaw, including the MCP setup and user-scoped authentication behind it

This guide explains how to let users use your app via OpenClaw. You provide a standard MCP service for your app and register an integration in Labs, so OpenClaw or other agents can call your app through SecondMe while the platform forwards an app-scoped user access token to your service at runtime.

SecondMe already provides the OpenClaw Skill. Once your app is connected, users can discover and use your app capabilities directly through OpenClaw, which can drive more exposure, calls, and real usage for your app.

Call Flow

1. Prepare an MCP Service for Your App

To let OpenClaw use your app, first expose a standard MCP server for it with at least one HTTP MCP endpoint, for example:

POST https://your-app.example.com/api/mcp

At minimum, this endpoint should support these JSON-RPC methods:

tools/list
tools/call

tools/list returns the tools available to the agent, and tools/call executes a tool.

Minimal tools/list request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list"
}

Example response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "tools": [
      {
        "name": "doudizhu_game_start",
        "description": "Start or resume a Dou Dizhu game",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

tools/call request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "doudizhu_game_start",
    "arguments": {}
  }
}

2. Configure the App in SecondMe

To let OpenClaw discover and call your app, create the integration in the console:

SecondMe Developer Console

In practice, the form is usually grouped into:

Skill Metadata
Prompts
Actions
MCP Configuration
OAuth Binding
Environment Bindings

Complete example:

{
  "skill": {
    "key": "doudizhu",
    "displayName": "Dou Dizhu",
    "description": "Start or resume a Dou Dizhu game for the current user.",
    "keywords": ["game", "doudizhu", "card"]
  },
  "prompts": {
    "activationShort": "Play Dou Dizhu",
    "activationLong": "Start a new Dou Dizhu game or resume the user's current game.",
    "systemSummary": "Use this integration to start or resume a Dou Dizhu session for the authenticated user."
  },
  "actions": [
    {
      "name": "Start Game",
      "description": "Start or resume a Dou Dizhu game for the current user.",
      "toolName": "doudizhu_game_start",
      "displayHint": "Start game",
      "payloadTemplate": {}
    },
    {
      "name": "Get Game State",
      "description": "Get the current or latest Dou Dizhu game state.",
      "toolName": "doudizhu_game_get_state",
      "displayHint": "View game state",
      "payloadTemplate": {
        "game_id": "{{game_id}}"
      }
    }
  ],
  "mcp": {
    "endpoint": "https://your-app.example.com/api/mcp",
    "timeoutMs": 15000,
    "authMode": "bearer_token",
    "toolAllow": ["doudizhu_game_start", "doudizhu_game_get_state"],
    "headersTemplate": {}
  },
  "oauth": {
    "appId": "your_oauth_app_id",
    "requiredScopes": ["userinfo"]
  },
  "environments": {
    "pre": {
      "enabled": true,
      "endpointOverride": "https://pre-your-app.example.com/api/mcp",
      "secrets": {
        "API_KEY": "pre_xxx"
      }
    },
    "prod": {
      "enabled": true,
      "endpointOverride": "https://your-app.example.com/api/mcp",
      "secrets": {
        "API_KEY": "prod_xxx",
        "token": "lba_at_example"
      }
    }
  }
}

Field Guide

Skill Metadata

Integration Key: Required. Use only lowercase letters, digits, and -.
Display Name: Required. The human-facing name shown in the product.
Description: Required. A short description of what the integration does.
Keywords: Optional. Helps search and categorization.

Prompts

Activation Short: Required. A short trigger phrase or compact title.
Activation Long: Required. A fuller activation description that tells the agent when to use the integration.
System Summary: Required. A concise system-level summary of the integration's capability boundary.

Actions

At least one action is required.
Each action should include Action Name, Description, and Tool Name.
Tool Name must exactly match the tools[].name returned by tools/list.
Display Hint: Optional. A UI-facing display hint.
Payload Template (JSON): Optional. Default JSON arguments for the tool.

MCP Configuration

MCP Endpoint: Required. Your HTTP MCP endpoint, for example https://your-app.example.com/api/mcp.
Timeout (ms): Optional. Set this based on expected tool latency.
Auth Mode: Optional. none and bearer_token are currently supported; header_template is not available yet.
Allowed Tools: The page may not enforce this as required, but you should explicitly set the tools you intend to expose.
Headers Template: Not available yet. No configuration is needed for now.

OAuth Binding

OAuth App ID: Required. The backend also validates that the app exists.
Required Scopes: Optional, but you should explicitly list the scopes the runtime path really needs. If your service calls /api/secondme/user/info, it usually needs at least userinfo.

Environment Bindings

pre and prod each keep their own environment-specific configuration.
Enabled: Controls whether the environment is active.
Endpoint Override: Optional. Override the endpoint for that environment.
Secrets: Optional. If your endpoint or header template uses placeholders such as {{token}} or {{API_KEY}}, provide matching key/value pairs here for that environment.

Practical Notes

Keep actions[].toolName and mcp.toolAllow aligned with the exact tools[].name values returned by tools/list.
If authMode = bearer_token and you do not hardcode an Authorization header in the template, the platform will typically try to auto-fill Authorization: Bearer <token> from the environment's token secret.
header_template is not available yet, so you do not need to configure Headers Template for now.
The most common configuration mistakes are a wrong OAuth App ID, missing Required Scopes, or mismatches between Allowed Tools, actions, and actual tool definitions.

actions[].toolName and mcp.toolAllow must exactly match the tools[].name values returned by tools/list.

3. How OpenClaw Calls Your App

At runtime, OpenClaw or other agents do not call your MCP server directly. They call the platform MCP proxy bound to the integration:

POST /rest/third-party-agent/v1/mcp/{integrationKey}/rpc

The platform then handles authentication and forwarding in this order:

It checks whether the current user has already authorized the app bound by oauth.appId.
It exchanges an app-scoped user OAuth access token for that app.
It forwards the incoming JSON-RPC request to your MCP server.
The forwarded request includes:

Authorization: Bearer lba_at_...

You should not receive or parse the main-site login token, and you should not depend on any sm-* token to identify the user.

4. Resolve the Current User in Your App

The token forwarded to your MCP service is the app-scoped user token issued by the platform. To resolve the current SecondMe user, call:

GET https://api.mindverse.com/gate/lab/api/secondme/user/info

Read:

data.userId

Do not read top-level id or data.id.

Typical response:

{
  "code": 0,
  "data": {
    "userId": "2499",
    "name": "xxx",
    "avatar": "https://..."
  }
}

5. Required Permissions for Your App

If your service needs to identify the current user through /api/secondme/user/info, the app authorization must include:

userinfo

A common source of confusion is that the platform prefers to sign the external token with the scopes the user has already granted to that app. If the existing grant does not include userinfo, your call to /api/secondme/user/info will still fail with 403.

6. Recommended App-Side Implementation

Resolve the token and current user as soon as the tool request enters your service:

const token = req.headers.authorization?.replace(/^Bearer\s+/, "");

if (!token) {
  throw new Error("missing bearer token");
}

const response = await fetch(
  "https://api.mindverse.com/gate/lab/api/secondme/user/info",
  {
    headers: { Authorization: `Bearer ${token}` }
  }
);

const userInfo = await response.json();
const userId = userInfo?.data?.userId;

if (!userId) {
  throw new Error("missing userId");
}

// Use userId as the stable business identity in your service.

7. Common Integration Issues

The most common integration issues are:

mcp.toolAllow does not match the tool name returned by tools/list
actions[].toolName does not match mcp.toolAllow
your service reads id instead of data.userId
the user never granted userinfo to the app
a 403 scope error from /api/secondme/user/info is misread as "the token has no user id"
the integration is bound to one oauth.appId, but the user authorized a different app

8. Integration Checklist

Debug in this order:

Confirm tools/list returns the expected tool definitions.
Confirm actions[].toolName and mcp.toolAllow exactly match the tool names.
Confirm the platform successfully exchanged the user-scoped token for the app.
Confirm your MCP service received Authorization: Bearer lba_at_*.
Confirm /api/secondme/user/info returned data.userId.
If the user info call returns 403, check whether the user's existing grant for that app includes userinfo.

Next Steps

Authentication Overview - Understand the platform OAuth2 model
OAuth2 Guide - Review the authorization code flow
SecondMe API - See APIs commonly used with the forwarded user token

Use Apps via OpenClaw

On this page