MCP interface
Understand MCP authentication, discovery, and product context.
Connect an AI client to https://mcp.lepsto.com to discover and call Lepsto operations over HTTP using JSON-RPC 2.0. The endpoint is shared across products and keeps no state between calls: each product-scoped call names its product in an argument.
For setup steps, see Connect Lepsto MCP.
Credentials
Method | Use it for | Behavior |
|---|---|---|
OAuth 2.1 authorization code flow with PKCE | An interactive client | You approve access in the browser; the client receives a short-lived token. |
Static API key as a bearer credential | A headless client | Create the key on the product’s Developer page, then supply it through the client’s credential settings. |
A static API key is bound to its associated product. With a key, the product argument may be omitted and the key’s product is used. A call whose product argument names a different product is refused with no_tool_permission, even if the key’s creator belongs to that product. This is the same boundary as REST; see product context by credential.
A key is checked on every request. Revoking it stops subsequent calls using that key. See API-key management for creation and revocation.
Without credentials, the endpoint returns 401 with a WWW-Authenticate header pointing to https://mcp.lepsto.com/.well-known/oauth-protected-resource. A rejected credential receives no discovery pointer: the client must repair its existing authentication.
Discovery and calls
tools/list returns the tool catalog with JSON Schemas for each tool’s arguments. The list is the same for every caller and does not change during a connection, so the server sends no tools/list_changed notification. tools/call invokes a named operation with those arguments. Permissions are checked on each call: a successful connection does not give an agent every platform permission.
Read-only tools carry a read-only annotation. Treat an unannotated tool as potentially changing state.
Names commonly follow <namespace>_<resource>_<action>. Actions can contain hyphens, as in organization_product_list-members. Read the returned schema instead of deriving an input field from the name.
User and product scope
Scope | Required context | Example |
|---|---|---|
user | An authenticated identity; the operation performs its own membership or organization-role checks. Takes no product_id. | |
product | An authenticated identity, a required product argument ( product_id, or productId where the tool declares it), and permission for the operation in that product. |
A user-scoped operation is not a permission you can add to a product role. OAuth identity scopes such as openid are also distinct from product permissions.
There is no product selection over MCP. Every product-scoped tool takes the product as an argument: product_id, or productId where the tool declares it. The tool schema shows which. The server adds a required product_id to the input schema of each product-scoped tool that does not already declare its own product argument; a tool such as organization_product_list-members keeps its productId and gets no product_id. Get the ID from organization_product_list and pass it on each call. A call sets the product for that call only, so an agent can work in two products without switching. The product-selection tools are not offered over MCP; calling one, like calling any unknown tool name, returns Unknown tool. The web app keeps its own active product, which does not affect MCP calls.
Refusals
A refused call is a tool error: the response is HTTP 200 with isError: true, and the error text starts with a machine-readable code.
Code | Meaning | Next action |
|---|---|---|
product_id_required | A product-scoped call had no product argument, and the credential is not an API key bound to a product. | List products with organization_product_list and repeat the call with the product argument the tool schema declares. |
no_tool_permission | The caller may not run this tool in that product: no grant for the operation, not a member, an unknown product, or an API key bound to another product. These cases return the same code on purpose. | Check the product ID, your product access and role permissions; with an API key, use a key created in that product. |
A missing or invalid token is still refused at the HTTP level with 401.
Transport
The server is stateless and accepts JSON-RPC over POST only. It issues no MCP session ID and opens no server-sent event stream.
Request | Response |
|---|---|
POST with Content-Type: application/json and one JSON-RPC message | The result, or a JSON-RPC error |
GET or DELETE | 405 |
A JSON array (a batch of messages) | 400 with JSON-RPC error -32600 |
Any other Content-Type | 415 |
When a tool is renamed, Lepsto retains its old name for one release cycle with a deprecation description pointing to the replacement. Check the live list before invoking a saved tool name.