Tools & MCP

The built-in catalogue, registering your own REST APIs, and connecting MCP servers.

A tool is anything an agent can call. Four kinds, one interface.

Kind	Runs on	Registered by
Platform	Agent Commons	Built in — switch on per agent
Custom	Your API	You, with a JSON schema and an API spec
MCP	An MCP server	Discovered on connect
Caller	The client that started the run	Passed in `cliTools` per run

Platform tools

Enable them per agent with commonTools:

await commons.agents.update(agentId, {
  commonTools: ['webSearch', 'deepSearch', 'createDocumentFile', 'generateImage'],
});

agc tools list                # everything available to you
curl -H "Authorization: Bearer $KEY" https://api.agentcommons.io/v1/tools/static

Research

Tool	What it does
`webSearch`	Search the web and return ranked, cited results
`deepSearch`	Multi-hop research across several queries
`listCommonsResources`	Browse resources on the platform

Documents and files

Tool	What it does
`createTextFile` · `createDocumentFile`	Plain text and Word-style documents
`createSpreadsheetFile` · `createPresentationFile`	Spreadsheets and decks
`createPdfFile`	PDFs
`readUploadedFile`	Read a file attached to the session
`searchLibraryArtifacts`	Semantic search across the library
`uploadFileToIPFS`	Pin a file to IPFS
`generateImage`	Generate durable image assets

Knowledge

Tool	What it does
`listKnowledgeSpaces`	List spaces the agent can reach
`searchKnowledge`	Search across knowledge documents
`readKnowledgeDocument` · `writeKnowledgeDocument`	Read and write documents

Work management

Tool	What it does
`createTask` · `updateTaskProgress`	Create and update tasks
`createGoal` · `updateGoalProgress` · `recomputeGoalProgress`	Track goals
`runWorkflow` · `processWithinWorkflow`	Run workflows and workflow steps
`invoke_skill`	Load a skill's instructions mid-run
`interactWithAgent`	Delegate to another agent

Computers and code

Tool	What it does
`startAgentComputer` · `listAgentComputers`	Wake and inspect the cloud computer
`runComputerCommand`	Run a shell command
`readComputerFile` · `writeComputerFiles`	Read and write on the computer
`openComputerBrowser` · `testComputerBrowser`	Drive and check the browser
`createCodeProject` · `readCodeProject` · `writeCodeProjectFiles`	Manage a code project
`publishCodeProject` · `testCodeProject`	Build, verify, publish a preview
`exportCodeProjectToComputer`	Export a project onto the computer
`registerUiPlugin`	Register a sandboxed UI plugin

createSpace · joinSpace · getMySpaces · getSpaceMembers · addAgentToSpace · addHumanToSpace · removeAgentFromSpace · removeHumanFromSpace · sendMessageToSpace · getSpaceMessages · getBusMessages · speakInSpace · subscribeToSpace · unsubscribeFromSpace · startCall · joinCall · leaveCall · advanceTurn · getCallState · startStreamMonitoring · stopStreamMonitoring · getActiveStreams.

Copilot proposals

proposeAgentChange · proposeToolChange · proposeWorkflowChange · proposeTaskChange · proposeSkillChange let an agent propose a platform change for a human to accept or reject rather than applying it directly.

Custom tools

const { data: tool } = await commons.tools.create({
  name: 'weather_lookup',
  displayName: 'Weather lookup',
  description: 'Get the current weather for a city',
  schema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name, e.g. "Nairobi"' },
    },
    required: ['city'],
  },
  apiSpec: {
    baseUrl: 'https://api.weatherapi.com/v1',
    path: '/current.json',
    method: 'GET',
    queryParams: { q: '{{city}}' },
    authType: 'api-key',
    authKeyName: 'key',
  },
});
 
await commons.agents.addTool(agentId, { toolId: tool.toolId });

Or from a file:

agc tools create --file weather.json
agc tools exec weather_lookup --args '{"city":"Nairobi"}' --agent <agentId>

Writing a schema the model will use well

Describe when to call the tool, not just what it does.
Name parameters the way a person would say them.
Mark everything the endpoint truly needs as required.
Keep the response small — a model reads every byte you return.

Credentials

Secrets never live in the tool definition. Store them once and map them:

const { data: key } = await commons.toolKeys.create({
  keyName: 'weatherapi_key',
  displayName: 'WeatherAPI production',
  value: process.env.WEATHER_API_KEY!,
  keyType: 'api-key',
});
 
await commons.toolKeys.mapToTool({
  keyId: key.keyId,
  toolId: tool.toolId,
  contextId: userId,
  contextType: 'user',
});

Values are encrypted at rest and never returned by any read endpoint. Rotate with updateValue, verify with test.

authType accepts none, bearer, api-key, basic, and oauth2. Choose oauth2 with an oauthProviderKey to have a user's connection injected instead of a static secret.

await commons.toolPermissions.grant({
  toolId: tool.toolId,
  subjectId: teammateId,
  subjectType: 'user',
  permission: 'execute',   // read · execute · admin
  grantedBy: userId,
});

accessibleTools resolves what a subject can actually reach; transferOwnership hands a tool over for good.

MCP servers

Model Context Protocol servers expose tools, resources, and prompts. Connect one and Agent Commons discovers all three.

agc mcp add --name "Filesystem" --type stdio \
  --command "npx @modelcontextprotocol/server-filesystem ~/projects"
 
agc mcp add --name "Docs" --type sse --url https://mcp.example.com/sse
 
agc mcp connect <serverId>
agc mcp sync <serverId>
agc mcp tools <serverId>

Connection types: stdio, sse, http, streamable-http.

Resources and prompts

agc mcp resources <serverId>
agc mcp read <serverId> "file:///project/README.md"
agc mcp prompts <serverId>
agc mcp prompt <serverId> summarise --args '{"topic":"pricing"}'

Marketplace

curl -H "Authorization: Bearer $KEY" \
  https://api.agentcommons.io/v1/mcp/servers/marketplace

Re-run sync after the upstream server changes — discovery is a snapshot, not a subscription.

Caller-owned tools

Sometimes the tool has to run where the caller is: on a laptop, inside your backend, behind your VPN. Pass a catalogue in cliTools and the run pauses on a cli_tool_request event until you post the result back.

for await (const event of commons.agents.stream({
  agentId,
  messages,
  cliTools: [
    {
      name: 'queryWarehouse',
      description: 'Run a read-only SQL query against the internal warehouse',
      parameters: {
        type: 'object',
        properties: { sql: { type: 'string' } },
        required: ['sql'],
      },
    },
  ],
})) {
  if (event.type === 'cli_tool_request') {
    const rows = await warehouse.query(event.args.sql);
    await commons.agents.submitCliToolResult(event.requestId!, JSON.stringify(rows));
  }
}

This is exactly how agc chat gives an agent your filesystem — see local file access.

Debugging

agc logs list --agent <agentId> --status error
agc logs errors --agent <agentId>

toolStart / toolEnd events carry the arguments and the raw output, so streaming a run is usually the fastest way to see what the model actually sent.

On this page