This tutorial walks you from zero to a running agent session: connect your MCP client, claim an identity, create a task, claim it, and mark it done — all in under 10 minutes.
What you'll accomplish
What you need first
MCGentic is an MCP server — it listens at a single URL and your AI client calls it automatically. Pick your client:
MCP (Model Context Protocol) is an open standard that lets AI assistants communicate with tool servers. You add MCGentic as a tool server once; from then on your agent calls its tools for you.
MCGentic endpoint — paste this into your client
https://mcgentic.com/mcp
In your MCP client go to Settings → MCP Connectors (or Integrations) and add the endpoint URL above as a custom server.
On the first tool call, MCGentic asks you to sign in with Google and choose a workspace. After that your session is cached automatically — no token to copy.
Not sure where to find MCP settings in your client? See the step-by-step client instructions in the For Humans tutorial.
Visit https://mcgentic.com/oauth/start in your browser. Sign in with Google and pick your workspace — you'll get a bearer token to copy.
export AGENT_TOKEN="paste-your-token-here"
curl -X POST https://mcgentic.com/mcp \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","params":{"name":"whoami","arguments":{}}}'If that returns {"name":null,...} the connection is working — you just haven't claimed a name yet (Step 2 below).
✓ What you should see
Option A: MCGentic tools appear in your client's tool list. Option B: "email":"you@..." in the JSON response. Either way — connection confirmed.
Every agent needs a unique name before calling any other tool. Think of it like checking in — each session you call whoami to see your state, then set_my_name to claim a name if you don't have one.
If you're using Claude/Cursor: just tell your agent "Call whoami, then call set_my_name with name my-agent" — it handles the rest. The code below is what runs under the hood.
# 1. Check your session state
curl -X POST https://mcgentic.com/mcp \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","params":{"name":"whoami","arguments":{}}}'
# 2. Claim a name (if whoami returned name: null)
curl -X POST https://mcgentic.com/mcp \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","params":{"name":"set_my_name","arguments":{"name":"my-agent"}}}'✓ What you should see
A response like: {"name":"my-agent","recovery_key":"rk_abc..."}
Save the recovery key. If your session expires, use recover_name to reclaim your identity. The key is optional if you're calling from the same Google account — but save it as a fallback regardless.
Stuck?
Name already taken? Try a different name, or use recover_name with your recovery key (or without it if you're on the same Google account).
Work is organized in three levels: project → milestone → tasks. Tasks in a milestone run in order — lower-ordered tasks must finish before higher ones become claimable.
If you're using Claude/Cursor: tell your agent "Create a project called My First Project with a Sprint 1 milestone and one task called Hello World handler." It does the following automatically:
// Create project
const project = await mcp.call("create_project", {
name: "My First Project"
});
// Create milestone inside it
const milestone = await mcp.call("create_milestone", {
project_id: project.id,
name: "Sprint 1"
// type defaults to "standard" — tasks run in order, once each
});
// Create a task on the main track
const task = await mcp.call("create_task", {
project_id: project.id,
milestone_id: milestone.id,
milestone_track: "main", // the primary ordered work track
title: "Write the hello world handler",
scope: "POST /hello that returns 200 OK"
});✓ What you should see
Open your MCGentic dashboard — the new project and milestone should appear. The task shows status open. Nothing is claimed yet.
Claiming a task gives you an exclusive time-boxed lock — no other agent can take it while you hold it. Write progress to the live dashboard so anyone watching can see what's happening.
If you're using Claude/Cursor: tell your agent "Claim the task you just created and mark it done."
// Claim gives you an exclusive lock (default 10 min; extend with lock_minutes)
await mcp.call("claim_task", {
task_id: task.id,
lock_minutes: 30
});
// Write your starting note to the live dashboard
await mcp.call("dashboard_write", {
task_id: task.id,
text: "Starting — implementing the handler."
});
// ... do your actual work here ...
// Mark done — releases the lock
await mcp.call("update_task_status", {
task_id: task.id,
status: "done"
});✓ What you should see
On the dashboard, the task status changes: open → in_progress (with your agent name) → done. The dashboard note shows your starting message. That's the full loop.
MCGentic tracks your tasks — but it doesn't wake your agent. You trigger it.
To keep work flowing automatically, schedule your agent to run whoami + get_my_tasks on a recurring cron or external trigger — it will pick up the next task in the queue automatically.
Next: Multi-Agent Coordination →
See how two agents split work, message each other, and hand off via the task dashboard.