// agents

Agent tools and the MCP gateway

What a deployed agent can call. Its own MCP endpoint and key, a tool list built from its own config, grouped or per-operation listing, the config fields that add or remove tools, how argument schemas are made, and where each call shows up afterwards.

A deployed agent reaches its superagnt_ tools through the superagnt_ MCP gateway. What the gateway serves an agent is built from that agent's own config, not from the workspace MCP server you connect your own client to, so two agents in the same workspace can see entirely different tools.

This page covers what a deployed agent gets. How tools are grouped into families and how they are named is on Tools and tool families. The act, ask and always_ask levels that decide whether a call runs or waits for a person are on Permissions and approvals.

The agent's own endpoint

Each deployed agent has an MCP endpoint of its own:

agent endpointtext

https://api.superagnt.com/runtime/agents/<agent-id>/mcp

Deploying the agent mints a key that belongs to that one agent. The runtime that runs the agent sends it as a bearer token on every request, so nobody copies or pastes it, and it is not listed with your workspace API keys. A workspace API key or another agent's key gets a 403. Archiving the agent revokes its key.

The endpoint speaks MCP over Streamable HTTP. A tools/call that carries a progress token is answered as a stream that sends a progress notification about every 20 seconds until the result arrives, so a long call, such as a TypeScript skill run, does not time out in the client.

An agent on superagnt_'s own runtime makes the same calls in-process instead of over HTTP. It is held to the same tool list, permission gate and dispatch.

Built from the agent's config

The agent's config holds one flat list of the tools it was given. Each entry points at one operation of a data source or a connection, a built-in utility, a Slack or iMessage connector tool, or a tool on a remote MCP server. The gateway turns every entry into the tool it names. An entry that no longer resolves, such as an operation renamed upstream or a remote MCP server that was disconnected, is left out, and the agent's other tools keep working.

On top of that list, some tools are always served and others come from switches on the config, both below. A config change reaches a deployed agent on its next session.

What a deployed agent never gets

A workspace's default MCP server carries twelve control tools: agnt_onboarding, agnt_platform_map, agnt_tools_search, agnt_tools_enable, agnt_tools_disable, agnt_tools_list_enabled, agnt_subscription_get, agnt_subscription_preview, agnt_subscription_change, agnt_setup_claim, agnt_bounties_list and agnt_bounties_claim. None of them reaches a deployed agent, so an agent can neither turn on tools for itself nor touch the plan. When an agent is missing a tool, it files agnt_request_config_change, and the change is proposed in the Agnt Wizard for a person to approve.

The families that manage the platform stay off deployed agents too: agent lifecycle, schedules, queue and webhook management, knowledge base management, platform guidance, data pipeline management, vendor sync management, and Slack and iMessage bindings. They live on the workspace MCP server and in the Agnt Wizard.

Over the endpoint, a call to a name that is not on the agent's list fails with the JSON-RPC error Unknown tool '<name>'.

Always served

Every deployed agent gets these, whatever its config says:

Tools	What they are for
`agnt_files_list`, `agnt_files_get`, `agnt_files_read`, `agnt_files_upload`	Workspace files.
`agnt_queues_enqueue`, `agnt_queues_enqueue_batch`, `agnt_queues_list`, `agnt_queues_list_items`	Putting items on a queue and reading them back. Any queue in the workspace.
`agnt_data_job_submit`	Feeding a data pipeline in the workspace. Withheld when `data_jobs_enabled` is `false`.
`agnt_datetime_now`	The real current date and time.
`agnt_support_docs_search`, `agnt_support_tickets_list`, `agnt_support_ticket_get`, `agnt_support_ticket_create`, `agnt_support_ticket_reply`	Asking the superagnt_ team for help. See Getting help.
`agnt_request_config_change`, `agnt_list_config_requests`	Asking a person to change the agent's config, and checking what it already asked.
`agnt_update_self_directives`	Rewriting its own standing directives: a block of up to 4,000 characters added to its system prompt from its next session.

Switched by the config

These fields on the agent's config add or remove tools. The middle column is what a new agent starts with.

Field	New agent	Effect on the tool list
`workspace_db.enabled`	`true`	Serves `agnt_db_status`, `agnt_db_list_tables`, `agnt_db_list_extensions`, `agnt_db_list_migrations`, `agnt_db_select` and `agnt_db_execute_sql`, plus `agnt_sync_status` and `agnt_sync_changes` for vendor syncs. `false` removes all of them.
`workspace_db.read_only`	`false`	While `false`, also serves `agnt_db_insert`, `agnt_db_upsert`, `agnt_db_update`, `agnt_db_delete` and `agnt_db_load_csv`. `true` removes them and runs every `agnt_db_execute_sql` statement read-only.
`workspace_db.allow_apply_migration`	`false`	`true` adds `agnt_db_apply_migration` for schema changes. Ignored on a read-only agent.
`workspace_db.table_allowlist`	every table	Removes no tool. Reads, writes and `agnt_db_execute_sql` are held to the listed tables, and `agnt_db_list_tables` shows only those.
`connections_db.postgres_enabled`	off	Adds `connection_postgres_query` and `connection_postgres_schema` for the Postgres database the workspace connected.
`connections_db.supabase_enabled`	off	Adds `connection_supabase_query` and `connection_supabase_schema` for the Supabase projects the workspace allowlisted.
`document_collection_ids`	empty	Any collection adds `agnt_documents_search` and `agnt_documents_read`, and every call is held to the listed collections.
`observability_enabled`	off	Adds the read-only `agnt_observability_*` family, over every agent in the workspace.
`agent_invocation_enabled`	off	Adds `agnt_agents_dispatch`, `agnt_agents_session_start`, `agnt_agents_session_send` and `agnt_agents_session_poll`.
`dashboards_enabled`	off	Adds the `agnt_dashboards_*` tools the agent uses to read, draft and publish views on the workspace dashboard.
`code_execution.enabled`	off	Adds `agnt_skill_manifest`, plus `agnt_typescript_run_skill` and `agnt_typescript_skill_status` once the agent carries a TypeScript skill.
`data_jobs_enabled`	on	`false` removes `agnt_data_job_submit`.

The Agnt Wizard sets these fields when it builds or edits an agent. From an MCP client, agnt_agents_get returns the current config and agnt_agents_update_config patches every field above. What the database itself offers is on Workspace database, and how collections work is on Knowledge collections.

The Postgres and Supabase tools are served as soon as their field is on, connected or not. Their calls fail until the workspace connects that database.

Utilities you attach

The rest of the built-in utilities are entries in the tool list like any other tool: agnt_credits_balance and the agnt_usage_* tools, agnt_webhooks_send, agnt_webhooks_receive_recent and agnt_webhooks_inbound_url, escalate_to_human and notify_human, agnt_report, agnt_sessions_read (the agent's own past sessions), the agnt_memory_* tools, and the inbox triage and reminder tools (agnt_email_*).

Long-term memory follows the memory tools. An agent that carries any agnt_memory_* tool has memory, and an agent without them has none.

escalate_to_human, notify_human, agnt_report, agnt_sessions_read and the two document tools exist only on deployed agents. They act on the calling agent and its session, which a workspace MCP client does not have.

Grouped or per-operation

An agent lists its tools in one of two shapes, fixed for the agent's life when it is created:

Grouped: one tool per resource and risk level, with an action argument. agnt_db_read with action select runs agnt_db_select. Agents created in the superagnt app, by the Agnt Wizard or with agnt_agents_create list grouped tools.
Per-operation: one tool per operation. Agents the platform builds for you, such as your workspace's first agent, the inbox manager and hires, list per-operation tools, the shape their prompts were tested with. So do agents created before grouped tools existed.

Nothing switches an existing agent from one shape to the other, and grouping never widens what an agent can call. A grouped tool is listed only when the agent has at least one of its operations, its action list holds only those operations, and every per-operation name still works on a grouped agent. Permissions, approvals and usage always record the per-operation name.

For example, a read-only agent with the database on lists agnt_db_read with five actions and agnt_db_sql with the single action execute_sql. It has no agnt_db_write at all, and apply_migration is not among its agnt_db_sql actions.

Code in a TypeScript skill that calls tools through the SDK always sees per-operation names. The grouped surface in full is on Grouped tools.

How argument schemas are made

Where a tool's input schema comes from depends on the tool:

Data source and connection tools are generated from the operation's OpenAPI spec, apart from the mailbox and database tools below. Path and query parameters become arguments, typed as the spec types them (a string when it says nothing), and required where the spec requires them.
Their JSON request body's fields become top-level arguments too, not a nested object. A single body object argument appears only when the spec gives the body no usable schema.
Their credentials are never arguments. The gateway attaches the credential to the upstream request itself.
A spec field whose name has characters other than letters, digits, _, . and -, or runs past 64 characters, is left out of the schema.
The people and company lookups describe their cost caps, max_cost_cents and max_cost_cents_per_record, with the range in cents that the endpoint accepts.
Remote MCP tools use the input schema their server publishes.
Built-in agnt_* tools, the Slack and iMessage tools, the Gmail and Outlook mailbox actions and the Postgres and Supabase database tools carry schemas written by the superagnt_ team.
A grouped tool merges its operations' arguments and adds action. The action picks the operation, and only that operation's arguments are passed on.

Grouped data tools also take response_format, response_fields and response_limit, and answer in compact markdown unless asked otherwise. See Response views.

What you can see afterwards

Every call leaves a trace in the superagnt app:

Sessions tab on the agent: every tool call in the transcript, with the arguments the agent sent and the result or error it got back. See Sessions, runs and observability.
Approvals tab on the agent: the calls the permission gate paused, waiting for a person. See Permissions and approvals.
Analytics tab on the agent: its most-called tools with call count, spend and errors, beside its error rate, average latency and its AI and data spend, over 7, 30 or 90 days.
Usage page: the same calls among every API call in the workspace, with provider, cost, status and latency. Open a row to see a data call's request and response.

The Analytics and Usage records cover calls to data sources, vendor connections and remote MCP servers. They count a call under its per-operation name, so a call made through a grouped tool counts under the operation it ran. A connection or remote MCP call keeps only metadata, such as the vendor, the path and the upstream status, never the records it carried.

Built-in agnt_* tools, the Slack and iMessage tools, the Gmail and Outlook mailbox actions and the Postgres and Supabase database tools write no usage rows. Read those calls in the session transcript. How every call and model token is recorded, and how to read it back over REST or with the agnt_usage_* tools, is on Usage.