MCP server

An agent reads with the permissions of the user it authenticates as. Before it can connect, you need two things:

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

A catalogue is built per caller. 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 meant exactly. A permission that depends on something the call carries, such as a query parameter or the request body, cannot be decided while the listing is built, 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 known, so it decides. A permission such as path-prefix('/orders') and equals(@subscription.plan, 'gold') announces /orders only to customers on the gold plan, which 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 permissions could allow: a role with only GET on a collection is not offered its writes. An action the permissions might allow is offered with a note: for a write whose rule reads a query parameter, the catalogue says that the outcome depends on what the call carries.

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). 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 these operations.

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

Two keys of a resource’s mcp metadata override all of this. Both decide what is announced; the permissions still decide what may be read:

hide_from_roles is checked first and wins over show_if. In the console both are under Catalogue visibility, below each published resource, as Hidden from and Shown only if.

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

Give each one a type and a description. Without a description, the agent knows only that the parameter exists, and guesses the rest.

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. Many clients, Claude Desktop among them, list only plain resources, so the aggregation may not appear there. It is still available: the agent finds it with list_apis and runs it with call_api, and the server says so 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. In real use 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 a checkbox shows which ones already exist:

Do all runs the unchecked items in order. It writes ordinary users, permissions, schemas and keys under those names, which you can change on the Users, Permissions, Schemas and API Keys pages. A permission applies within 20 seconds.

For a quick try, the root user created with the service works too, and sees everything.

Each identity gets its own catalogue, and this panel compares them. Add up to eight identities, such as an API key for each role or a user on each plan, give each a label, type its key or password, and click Read the catalogues.

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

Actions. Click a resource to see its actions for every identity, with the actions on its elements kept apart from those on the resource itself: delete removes a document, drop removes the collection. ✓ means offered, ~ offered but decided by the call’s arguments (the note says which), ✗ refused by that identity’s permissions, and a dash means the resource is hidden from that identity. A row of ✗ on drop is normal: 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 the resource. So:

The identities and the expectations are saved with the service; the keys and passwords are not, so 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 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. Three things the matrices do not show:

Clients like Claude sign in with OAuth: 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 show it.

If you switched on Google in the OAuth section of the Sign-up and login page, the default login page offers it 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, like any new user, and the agent then works with that user’s roles. There is nothing else to configure: it uses the same client ID and secret as your app’s own sign-in.

The default page is https://c0ffee.ulabase.app/oauth/login. Under OAuth login page you can set your own, so the user sees your application’s login. It receives the OAuth parameters as a query string and must POST them, with 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, with * as a wildcard. It starts with the default list, which covers Claude and the desktop clients. Your list replaces the default, so if you edit it, keep the claude.ai entry or Claude can no longer connect.