Create an MCP Stack agent

Agents turn MCP servers into usable assistant experiences. A server exposes tools; an agent decides how to use those tools in conversation with a specific model, prompt, and connection state.

Agents combine model configuration, MCP server attachments, user context, and conversation state.

Before creating an agent#

Have at least one MCP server ready:

• The server should have a focused tool set.
• tools/list should pass.
• Gateway-backed servers should have working OAuth.
• Tool instructions should explain important writes.

Do not create the agent first and hope the tool surface becomes clear later. Agent quality depends on server quality.

Create the agent#

Create agents after the server tool surface is healthy. The agent workspace is where servers, model settings, instructions, and test conversations come together.

1. Open Agents.
2. Click Create Agent.
3. Enter a name.
4. Select one or more MCP servers.
5. Choose a model and provider.
6. Set reasoning effort if the selected model supports it.
7. Add a system prompt.
8. Save the agent.

CLI path#

mcpstack agents list --json
mcpstack agents get ag_support --json
mcpstack agents create --name "Support Assistant" --json

Attach MCP servers and model settings in the dashboard or via the agents API after creation.

API path#

Create an agent:

POST /api/v1/organizations/{orgId}/agents
Authorization: Bearer {token}
Content-Type: application/json
 
{
  "name": "Support Assistant",
  "model": "gpt-4.1",
  "provider": "openai",
  "systemPrompt": "You are a support assistant...",
  "mcpServerIds": ["srv_support"]
}

List agents:

GET /api/v1/organizations/{orgId}/agents
Authorization: Bearer {token}

Set agent budgets with PATCH .../budget for the agent pool and per-user defaults, and PUT .../external-users/{id}/budget for a single user's monthly cap.

System prompt starter#

Use a prompt that describes role, scope, tool boundaries, and confirmation rules.

You are a support operations assistant for Acme.
 
You can search tickets, read ticket history, and draft or apply ticket updates
using the connected MCP tools. Use read tools before write tools. Before
changing a ticket, confirm the ticket ID, customer, action, and final wording.
 
Do not invent API results. If a tool returns an error, explain the failure in
plain language and ask the user for the missing information or next step.

Attach the right servers#

Attach servers by task domain, not by organization chart.

Good agent boundaries:

• Support assistant: tickets, customers, account notes.
• Billing assistant: invoices, subscriptions, payment status.
• DevOps assistant: deployments, incidents, logs.

Avoid one giant agent with every company tool attached. It increases model confusion and increases the blast radius of a bad prompt.

Test the first conversation#

Test in this order:

1. Ask a read-only question that should call one tool.
2. Ask a question that should require clarification.
3. Ask for a write action that should require confirmation.
4. Disconnect or expire auth and confirm the agent asks to reconnect.
5. Review conversation and tool-call logs.

Agent readiness checklist#

Quick answer#

Before creating an agent, confirm you have a healthy MCP server; if not, finish server creation and smoke tests first. Then attach the server, select a model, write the system prompt, and run a read/write test plan.