MCP server

An agent reads with the permissions of whoever it authenticates as. Before one can connect, two things have to be in place:

A client that signs the user in through the browser, like Claude, uses a key too: it obtains one by signing in. The sign-in page becomes a consent step, role, duration and name within the apiKeys block of the user’s permission, and what Claude gets from /token is a ulak_ key with that role. So the two points above hold for Claude as for Cursor: the user needs a permission on /keys naming the roles a key may carry, and the chosen role needs its permissions. Without such a permission the sign-in falls back to the user’s own token, with every role the user holds; see The OAuth login page for how to forbid that.

A catalogue is built per caller. To decide what to announce, RESTHeart reads the permissions of the role the agent authenticated as and announces a resource as soon as one of them could allow a read of it.

"Could allow" is the exact wording. A permission that decides on something the call carries, a query parameter or the request body, cannot be decided while a listing is being composed, because there is no call yet: that part is left open and the resource is announced. The call itself is authorized as usual and may answer 403. A condition on who is asking is different: it is known, so it decides. A permission such as path-prefix('/orders') and equals(@subscription.plan, 'gold') announces /orders to a customer on the gold plan and to nobody else, something no list of roles could express, since every customer holds the same role.

The same rule decides a resource’s actions. A resource is described with the actions the caller’s own permissions could allow: a role holding only GET on a collection is not offered its writes. An action the permissions might allow is offered, with what the catalogue knows about it: a write whose rule reads a query parameter says that whether it goes through depends on what the call carries, because a listing does not have it.

A collection also publishes the operations on itself: reading and changing its properties, dropping it, its indexes, and the bulk writes. Each says what it acts on (delete removes one document, drop removes the collection with everything in it), and each needs two things: a permission matching the request, and a switch in that permission’s mongo block (allowManagementRequests, allowBulkPatch, allowBulkDelete). Those switches are off unless written, so by default nobody is offered them.

Your permissions are the only thing enforced, and for almost every policy they are also all the catalogue needs: Ulabase reads them and works the listing out by itself. One case needs telling, and what is at stake there is the accuracy of the listing, since the permission itself is enforced anyway: a permission whose condition is a predicate or a variable added by custom code that declares nothing about itself, such as is-premium() or @billing.tier. The catalogue cannot read it, so it does not guess: it announces the resource to everyone the rest of the rule admits. The same holds when access is decided by a custom authorizer, which has no predicate to read at all. The two keys below are how you say what those cases mean.

Two keys of a resource’s mcp metadata override all of this, and both decide what is announced; what may be read stays with the permissions:

hide_from_roles is decided first and wins over show_if too. Both are under Catalogue visibility, below each published resource.

An aggregation whose pipeline uses $var takes parameters, and the page lists them under the entry, one row each, driven by the pipeline itself: add a variable to the stages and the row appears.

Give each one a type and a description. Left undescribed, an agent is told the parameter exists and nothing more, which in practice means it guesses.

A value MongoDB stores in its own type takes that type: date, objectId, long or decimal. The agent is told to send {"$date": <epoch millis>} for a date, and the pipeline receives a date. As a string, a parameter compared with a date field matches nothing.

A parametric aggregation reaches the agent as a resource template, a different kind of entry from a plain resource, and many clients, Claude Desktop among them, list only plain resources. That absence is normal: the aggregation is there, the agent finds it with list_apis and runs it with call_api, and the server says as much in the instructions it sends when a client connects.

Creates a test user, its permission, a test collection and an API key, so you can connect an agent right away. Normally you define roles for agents, let your users issue API keys with those roles, write the permissions and publish resources; this panel makes a test version of each, and shows with a checkbox which ones already exist:

Do all runs the unchecked items in order. Everything it writes is what you would create yourself on the Users, Permissions, Schemas and API Keys pages, under those names, and can be changed there. A permission applies within 20 seconds.

To just try, the root user created with the service works too, and sees everything.

The catalogue is one per identity, so the useful question is what shape the catalogue has across them. Add up to eight identities, an API key for each role, a user on each plan, with a label each, type their key or password, and read the catalogues.

Resources. One row per resource, one column per identity: visible or hidden. Click a cell to record what that identity is meant to see; a cell that disagrees with its expectation is marked, and the count of failing expectations is at the top. Two rows deserve a second look: all visible for a resource that should be reserved, and all hidden for one you published on purpose.

Actions. Click a resource to see its actions for every identity, the ones on its elements apart from the ones on the resource itself: delete removes a document, drop removes the collection. ✓ offered, ~ offered but decided by the call’s arguments (the note says on what), ✗ refused by that identity’s permissions, and a dash when the resource is hidden from that identity. A row of ✗ on drop is the normal case: the data management operations need allowManagementRequests in the permission.

Reading it. The catalogue errs in one direction only: it never hides what a permission could allow, and when it cannot tell, it lists. So:

The identities and the expectations are saved with the service, the keys and passwords are not: type them again when you come back. Demo setup adds the identity agent with the credential it has just made.

Test with the credential the agent will actually use. A user’s password shows what the user sees; a key carries only the roles it was issued with, so its agent may see less. And three things the matrices do not show on their own:

Clients like Claude use OAuth authentication: when a user adds your service as a connector, Claude opens a login page where they enter their credentials for your service. Clients that use an API key, like Cursor and VS Code, never see it.

If you turned on Login with Google on the Sign-up, OAuth & Invitations page, the default login page offers it here too: a Continue with Google button above the username field. A user who has never signed in to your service gets an account on the spot, with whatever your service gives a new user, and the agent then works with that user’s roles. Nothing else to configure: the same client ID and secret, and the same providers, that your app’s own sign-in uses.

The default page is https://c0ffee.ulabase.app/oauth/login. Under OAuth Login Page you can set a custom one, so the user sees your application’s login: it receives the OAuth parameters as a query string and must POST them, plus the user’s credentials, to https://c0ffee.ulabase.app/authorize. The URL must be absolute, https:// or http://.

The same panel lists the allowed redirect URIs: the redirect_uri values /authorize accepts, * as a wildcard. It starts as the default list, which is what Claude and the desktop clients need. If you customise it, keep the claude.ai entry, or Claude can no longer connect: your list replaces the default, so what you leave out is gone.