Programmatic Integration
Integrate with LockMCP programmatically — from your own service or script, rather than through a desktop AI client. This is the documented path for Token Exchange connections, which can't use interactive browser login.
Everything a client needs is discoverable from the connection's MCP endpoint, so there is no separate portal page to copy values from.
When you need it
| Integrate programmatically when | Use Connect when |
|---|---|
| Your connection uses Token Exchange | Your connection uses Identity Brokering or Tenant Delegated |
| You're building a service that calls tools | People connect from Claude Desktop, Cursor or ChatGPT |
| You need code, not a config UI | You want the one-URL path |
If you're on Token Exchange, this isn't a preference — interactive browser OAuth is disabled for those connections by design, so this is the integration path.
What you start from
The MCP endpoint of the connection: copy it from Dashboard → Connect with the connection selected. It has the form:
https://<your-mcp-domain>/<workspace>/<connection>/mcpDiscovering the rest
The endpoint publishes standard OAuth metadata next to it, so a client finds everything else on its own:
Path (relative to https://<your-mcp-domain>/<workspace>/<connection>) | What it gives you |
|---|---|
/.well-known/oauth-protected-resource | Which authorization server protects this endpoint |
/.well-known/oauth-authorization-server | The token, authorization and registration endpoints |
/.well-known/openid-configuration | The same, in OpenID Connect form |
Clients register themselves through the registration endpoint (dynamic client registration), so there is no client ID or secret to copy into your service.
The flow
Programmatic integration follows the same shape as any MCP client:
- The client discovers OAuth metadata from the MCP endpoint.
- It receives an access token from the token endpoint.
- It calls the MCP endpoint with that token.
- It gets back the tool list — filtered to what the authenticated user's roles allow.
The difference from a desktop client is that no browser window opens: your service obtains the token directly.
Which tools you get
The tool list is scoped to what's actually available — published tools that the authenticating identity's roles can reach. If a tool you expect is missing, the cause is the same as everywhere else:
- The tool isn't published (Tool Catalog)
- No role has access to it (Assigning Tool Access)
Keeping credentials safe
Tokens your service obtains authenticate it. Treat them like any other secret:
- Load configuration from environment variables
- Never commit tokens, and never ship them in client-side code
- Re-authenticate rather than reusing a token that may have been exposed
A leaked token lets someone call your tools as your service. Because tool calls proxy to your real API, that's access to your data — not just to LockMCP.
Troubleshooting
| Symptom | Cause |
|---|---|
| Token request rejected | The connection isn't Active, or the client registration is stale — register again |
user not found — please log in to the Dashboard first | Expected on first use with Token Exchange — the user must sign in to the dashboard once |
unable to resolve signing key | Sending your IdP's own token instead of the LockMCP-issued one. See Token Exchange Auth Flow |
| Empty tool list | Nothing published, or no role access |
issuer not recognized | Calling the wrong connection's endpoint |
More in Token Exchange Troubleshooting.
Where to go next
- Token Exchange — the model this path serves
- Token Exchange Auth Flow — what the token exchange actually does
- Connecting AI Clients — the desktop-client path