Working with the agent
What an agent can do in your instance over MCP, what it can never do and what it needs to know from you.
Your instance is an MCP server at /mcp. Through it an agent such as Claude Code reaches structure, data, permissions and the files of the tools. It signs in with your access token and has at most your permissions.
How to start
- Set up the workspace and start the agent there.
- Ask it to call
start_herefirst. The answer names the instance, the room, the order of steps and the rules that cannot be corrected later. - Describe what you need: which details, who works with them, who may see what.
The agent then works in this order: create the collection, check it with a few rows, create the tool, release the tool to a role, name the owner.
What the agent needs to know from you
- Purpose and retention period. A new collection states both. The agent asks you for them and does not invent a period. The period is a number of months or unlimited.
- The owner of the tool. This is the person to ask about the tool. They must be an administrator. The agent enters the owner as long as nobody is named. After that only a person can change it, in the admin area.
- Who gets permissions. Permissions belong to roles. Name the role that is to use the tool.
The MCP tools
| Group | Tools |
|---|---|
| Getting started | start_here, whoami, get_agent_instructions |
| Structure | list_collections, describe_collection, describe_types, ensure_collection, ensure_index, discard_field, discard_collection |
| Data | query_records, count_records, aggregate_records, create_record, update_record, delete_record, describe_api |
| Roles and permissions | list_roles, describe_role, ensure_role, find_people, add_role_member, set_collection_grant, set_tool_grant |
| Groups and contexts | list_person_groups, ensure_person_group, add_person_group_member, give_person_group_role, list_contexts, ensure_context, map_context_value |
| Tool files | list_tools, scaffold_tool, read_tool_file, put_tool_files, check_tool, set_tool_owner, list_tool_errors, resolve_tool_error |
| Buckets | ensure_bucket, list_buckets |
A few of them are worth knowing:
ensure_collectiontakes the target state. A second call with the same content changes nothing. WithgrantToa role gets read and write permission in the same call. Without a grant nobody sees the data, not even whoever created the collection.scaffold_toolcreates a working tool for one collection in the draft. Form and table are built from the schema.check_toolsays whether a tool can be published and, if not, what is missing in which file.describe_apigives the HTTP calls for one collection with its real field names.list_tool_errorsshows errors a tool had in the browsers of its users.
query_records returns at most 20 rows per call. Files do not go into a bucket over MCP but over HTTP.
What the agent can never do
- Revoke permissions. A grant the agent has set can only be taken back in the admin area. So have it look with
describe_rolebefore it grants anything. - Delete structure in production. There is no tool that removes a collection or a field from production.
discard_fieldanddiscard_collectionwork only in the practice room and only on what never reached production. - Publish a tool. Everything the agent writes lands in the draft.
- Grant capabilities. A person grants
mail.sendandpeople.readto a role in the admin area. - Remove an index, a bucket or an owner.
The agent deletes single rows with delete_record if you have write permission on the collection.
Where the agent works
With a token for the practice room the agent sees only what was created there. Structure it creates then waits for a person to carry it over to production. It sees people under pseudonyms.
The agent can change structure and grant permissions only if you are an administrator yourself. If the instance answers with “no access”, whoami helps first: usually a grant is missing, not a structure.
Keeping the instructions current
get_agent_instructions returns the current rules for building tools as Markdown with a version. Put the block into the file your agent reads (CLAUDE.md, AGENTS.md, README.md). Called with the version the agent already has, it says whether that version is still current.