MCP tools

The Nomic MCP server turns each Nomic HTTP API operation into one tool, named after the operation. It adds three helper tools that start an agent and wait for it, a set of prompts, and two resources.

A client sees only the tools its API key can call. A key with the developer scope sees the developer tools, and admin tools appear only for keys with admin scopes whose owner is an organization admin. Each call still checks the key owner's access, so a tool never returns a project or file its owner can't open.

To see exactly what a key can call, use get_current_api_key, or read the nomic://catalog resource.

How tools work​

Arguments​

A tool takes one object that combines the operation's path parameters, query parameters, and JSON body fields. For example, get_artifact takes id and artifactId, and launch_agent takes prompt, projectId, fileIds, and the other body fields of POST /agents. Each tool's input schema lists its arguments, and the API reference describes them in full.

List tools take limit and cursor. When a result includes nextCursor, pass it as cursor to get the next page.

IDs are UUIDs. Get them from list and search tools: search_files for file IDs, list_projects for project IDs, list_workflows for workflow IDs.

Results and errors​

A successful call returns the API's JSON response as structured content, with the same JSON as text for clients that ignore structured content.

A failed call returns an error result with the API's status and error code:

{
  "status": 429,
  "code": "rate_limited",
  "message": "Rate limit exceeded",
  "retryAfterSec": 12
}

Tool types​

Each tool carries MCP annotations so clients can decide when to ask you for approval. The tables on this page use these types:

Scopes​

The Scope column names the scope a key needs. Broad scopes include the narrower ones under them: developer covers every developer:* scope, and admin covers every admin:* scope. Keys created in the Developer Console with the developer scope can call every developer tool.

Account​

Any valid key can call get_current_api_key. Use it to check a key before starting work.

Agents​

Agents run in the background. Start one with run_agent (or launch_agent), then read its answer with get_conversation and its outputs with get_artifact.

get_agent, get_conversation, and get_agent_usage also accept admin:analytics:read, which lets an admin key read any agent in the organization.

Start an agent​

A simple agent takes a prompt, plus optional files, project, and capabilities:

{
  "prompt": { "text": "Summarize the open items in the site visit report." },
  "projectId": "0199a3f2-5b1c-7d40-9e2a-3c8f1a6b2d10",
  "fileIds": ["0199a4c8-1f2e-7a33-8b5d-6e9c0d4f7a21"],
  "capabilities": { "webSearch": true }
}

To run a workflow, find it with list_workflows (its query matches names and descriptions), then pass workflowId. If the workflow has file inputs, pass workflowInputs instead of prompt, mapping each input name from the workflow's requestedFiles to a file ID, a list of file IDs, or null for an optional input you leave empty. Editors can pass workflowVersionId to run a version other than the released one.

Follow-ups can't attach new files. To work with new files, start a new agent.

What the wait tools return​

run_agent, followup_and_wait, and wait_for_agent return:

{
  "agentId": "0199b1e0-6c2d-7f18-a4e3-2b7d9c5e8f01",
  "timedOut": false,
  "agent": { "id": "0199b1e0-…", "status": "finished", "artifacts": [] }
}

agent is the same object get_agent returns. An agent is active while its status is waiting, running, or awaiting_tool, and done once it is finished, failed, or stopped.

A call waits up to 14 minutes. Pass timeoutMs to wait less. If the time runs out, the result has timedOut: true and the latest status, and the agent keeps running. Call wait_for_agent with agentId to keep waiting. Don't call run_agent again, which would start a second agent.

You can open any agent in Nomic at https://<your-domain>.nomic.ai/assistant/<agentId>.

Files​

PDFs and legacy Office files are processed after upload. Wait until get_file_status reports ready before you pass the file to a workflow.

upload_file takes the file as an object:

{
  "file": {
    "filename": "site-visit.pdf",
    "contentBase64": "JVBERi0xLjcK...",
    "mimeType": "application/pdf"
  },
  "path": "Field/Site visits/site-visit.pdf"
}

path includes the file name and creates any missing folders. Pass parentId instead to upload into an existing folder.

The client's model writes the base64 content into the call, so upload_file suits small files such as notes or short reports. For drawing sets and other large files, upload in the Nomic app or with POST /api/v0/files/upload, which accepts files up to 500 MB.

Workflows​

get_workflow and list_workflow_versions need edit access to the workflow, like opening it in the builder.

Author and improve a workflow​

create_workflow and update_workflow never release. Each returns a versionId; pass it to run_agent as workflowVersionId to test that version while everyone else keeps running the released one. Only editors can run a version other than the released one.

update_workflow edits the latest version in place only while it is unreleased and no agent has run it. After a run, the version is frozen and the next update writes a new version, so each run stays tied to the instructions it ran. To drop a candidate, pass an earlier version as baseVersionId.

When get_workflow returns isShared: true, releasing changes what other people run. Context files, tags, MCPs, and sharing are set in the builder, at the builderPath each response returns.

Projects​

Roles map to the app's names: admin is Admin, editor is Member, and viewer is Read-only. Changing a project or its members also requires admin access to that project. Organization admins can update any project.

Parse​

Parse works on uploaded files only, not files synced from an integration such as SharePoint or Google Drive. See Parse for the output format.

Codes​

See Code search for jurisdictions, code types, and the result format.

Budgets​

Budget tools need admin access to the budget. Organization admins can reach the organization budget and every project budget, and a project admin can reach that project's budget. Member limits must be turned on for a budget before set_budget_member_limits can change them.

Admin tools​

These tools appear only for keys with admin scopes, and only while the key's owner is an organization admin.

Users​

API keys​

Audit logs​

Integrations​

Analytics​

Analytics tools default to the last 30 days. See Analytics for the fields each one returns.

Prompts​

Prompts are ready-made instructions that walk the client through a task. Most clients list them as slash commands. A prompt appears only when the key can call every tool it uses.

Resources​

Limits​

Related​

• Nomic MCP server: connect a client.
• MCP for IT and admins: roll-out, access control, and auditing.
• API reference: every operation's parameters and responses.