Core Concepts

Five ideas explain almost everything about how LockMCP works. Read this once and the rest of the documentation will make sense.

The shape of it

Your workspace
│
├── Connection: "Billing API"          ← identity model, base URL, credentials
│   ├── API spec  →  Tools  →  published to the Tool Catalog
│   └── MCP endpoint  ←── AI clients connect here
│
├── Connection: "Support API"          ← its own identity model and endpoint
│   └── ...
│
└── Members & Access
    ├── Roles       ← what a group of people may do
    └── Members     ← the people, each holding roles

1. Workspace

Your organisation's account. Everything below lives inside it: connections, tools, members, roles, audit history, and billing.

Workspaces are fully isolated from one another. Your data is never visible to another workspace, and queries are scoped to your workspace at the database level rather than only in application code.

2. Connection

A connection is one API you're exposing to AI clients. It holds:

PropertyWhat it is
Base URLWhere your API lives
CredentialsHow LockMCP authenticates to your API, stored encrypted
Identity modelHow your users are recognised — see below
StatusWhere it is in onboarding: Intake → Pending verification → Provisioning → Provisioned → Active
MCP endpointThe URL AI clients connect to, unique to this connection

The important part: a workspace can have many connections, and each is configured independently. A "Billing API" connection and a "Support API" connection can use different identity models, different credentials and different tools, and each gets its own MCP endpoint.

A connection only serves tools once its status is Active.

3. Identity model

How a user proves who they are. Chosen per connection, in Step 1 of the wizard.

ModelWho authenticates the user
Identity BrokeringLockMCP
Token ExchangeYour existing identity provider
Tenant DelegatedYour application's own login page

Because this is per connection, it isn't a one-way decision — see Choosing an Identity Model.

Don't confuse this with the connection's credentials, which are how LockMCP authenticates to your API. Identity model is about your users; credentials are about your server. They're independent.

4. Tool

A tool is one thing an AI client can do — usually one endpoint of your API, like "create an invoice" or "search customers".

Tools come from an OpenAPI spec you upload. LockMCP reads the spec and generates a draft tool per operation, which you then refine and publish.

A tool has:

  • A name and description — this is what the AI reads to decide when to use it, so wording matters
  • An input schema — the parameters, their types, and which are required
  • A published state — draft tools are never served to AI clients
  • Role access — which roles may call it

Tools live in the Tool Catalog and are edited in Tool Studio.

5. Roles and members

Members are people who can use your connections. Roles are named bundles of access that you assign to members.

Every connection starts with two roles: an admin role and a standard member role. You can add more.

Access is decided by the pairing:

member  →  holds role(s)  →  role has access to tools  →  member can call those tools

A member with no role calls nothing. A published tool with no role granted access is invisible to everyone except admins. Both halves have to line up — this is the single most common source of "connected but no tools appear".

See Roles and Permissions.

How a tool call flows

Putting it together — what happens when an AI client calls a tool:

  1. The client connects to a connection's MCP endpoint and authenticates according to that connection's identity model.
  2. LockMCP resolves which member this is and which roles they hold.
  3. It returns only the published tools that those roles may call.
  4. When the AI calls one, LockMCP proxies the request to your API using the connection's stored credentials.
  5. The call is recorded in the audit log, attributed to that member.

Your API sees a normal HTTP request. Your users only ever reach what their roles allow.

Where to go next