Cursor turns your editor into an AI‑native workspace, but the heavy LLM calls can still slow you down. By offloading the Claude‑powered tool server to ECS Fargate you keep the IDE snappy while gaining unlimited scalability. This post shows exactly how to wire the two together.
Understanding Cursor’s Agent Mode
What is Agent Mode?
Cursor ships with a built‑in LLM (large language model) that can suggest code, refactor, or answer questions. When it needs to do something it can’t do locally—like running a test suite, reading a remote file, or calling a cloud service—it switches to Agent Mode. In this mode Cursor sends a tool call (an HTTP request) to a tiny web server you provide. The server does the work, talks to other services (for example AWS Bedrock’s Claude model), and sends a JSON payload back. Cursor then inserts the result into your editor as if it had generated the answer itself.
In plain English: Agent Mode is Cursor’s way of asking a helper program, “Hey, can you look this up for me?” The helper does the heavy lifting and tells Cursor what it found.
Minimal tool server (Node 22)
// file: tool-server.ts
import http from "node:http";
/**
* The shape of a request Cursor sends.
* `method` is the name of the tool (e.g., "runTests").
* `params` holds any arguments the tool needs.
*/
interface CursorRequest {
method: string;
params: Record<string, unknown>;
}
/**
* A very small HTTP server that listens on /tool.
* It pretends to call Claude on Bedrock and returns a dummy answer.
*/
const server = http.createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/tool") {
res.writeHead(404);
return res.end();
}
// Collect the request body
let body = "";
req.on("data", chunk => (body += chunk));
req.on("end", async () => {
const payload: CursorRequest = JSON.parse(body);
// Simulate a call to Claude – in real code you would use the Bedrock SDK.
const answer = {
result: `You asked for ${payload.method}, I would call Claude here.`,
};
// Cursor expects a 200 status and a JSON body.
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify(answer));
});
});
// Listen on the port you will expose to Cursor (default 8080).
server.listen(8080, () => {
console.log("✅ Tool server ready at http://0.0.0.0:8080/tool");
});
Why this matters – The server is tiny, has no state, and can be containerised. Cursor only cares about the HTTP contract, not the language you used to implement it.
Tip: Keep the server stateless; it makes scaling on Fargate trivial because any instance can answer any request.
Why Run the Claude Tool in ECS Fargate
Running the tool server on your laptop ties its performance to your local resources. A single slow request can freeze the whole editor. Moving the server to ECS Fargate (a managed container service) gives you three practical benefits:
- Isolation – The container runs in its own sandbox, so a crash or memory spike never touches your development machine.
- Predictable performance – You allocate CPU and memory up front, and Fargate guarantees that slice.
- Unlimited scaling – If your team grows or you start sending many concurrent tool calls, you can increase the desired count without touching code.
Think of it like a coffee shop: you could brew coffee in your kitchen (local server) and risk spilling everything, or you could rent a dedicated espresso machine in a café (Fargate) that always has the right pressure and temperature.
Key takeaway: A managed container platform removes the “my laptop is slow” variable, letting Cursor stay responsive.
Quick look at a Fargate task definition (JSON)
{
"family": "cursor-tool-task",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "256",
"memory": "512",
"containerDefinitions": [
{
"name": "tool-server",
"image": "public.ecr.aws/your-repo/tool-server:latest",
"portMappings": [{ "containerPort": 8080, "protocol": "tcp" }],
"environment": [{ "name": "BEDROCK_REGION", "value": "us-east-1" }]
}
]
}
The JSON above tells Fargate what container image to run, how much CPU/memory to give it, and that the container should listen on port 8080. The next section shows how to create this definition from code.
Step‑by‑Step: Deploying a Tool Server with the ECS SDK
We will use the @aws-sdk/client-ecs package, the official JavaScript/TypeScript client for Amazon ECS. The steps are:
- Create a cluster – a logical bucket for your tasks.
- Register a task definition – describes the container image and resources.
- Run a Fargate service – keeps the desired number of tasks alive.
- Add a security group – lets Cursor’s outbound traffic reach the service.
In plain English: Think of a cluster as a kitchen, a task definition as the recipe, and a service as the chef who keeps cooking the recipe as orders arrive.
1️⃣ Create a cluster
import {
ECSClient,
CreateClusterCommand,
RegisterTaskDefinitionCommand,
CreateServiceCommand,
} from "@aws-sdk/client-ecs";
const ecs = new ECSClient({ region: "us-east-1" });
async function createCluster(name: string) {
const cmd = new CreateClusterCommand({ clusterName: name });
const resp = await ecs.send(cmd);
console.log(`✅ Cluster "${name}" created with ARN ${resp.cluster?.clusterArn}`);
return resp.cluster?.clusterArn!;
}
2️⃣ Register the task definition
async function registerTaskDef() {
const cmd = new RegisterTaskDefinitionCommand({
family: "cursor-tool-task",
requiresCompatibilities: ["FARGATE"],
networkMode: "awsvpc",
cpu: "256", // 0.25 vCPU
memory: "512", // 0.5 GiB
containerDefinitions: [
{
name: "tool-server",
image: "public.ecr.aws/your-repo/tool-server:latest",
essential: true,
portMappings: [{ containerPort: 8080, protocol: "tcp" }],
environment: [{ name: "BEDROCK_REGION", value: "us-east-1" }],
logConfiguration: {
logDriver: "awslogs",
options: {
"awslogs-group": "/ecs/cursor-tool",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "tool",
},
},
},
],
});
const resp = await ecs.send(cmd);
console.log(`✅ Task definition registered: ${resp.taskDefinition?.taskDefinitionArn}`);
return resp.taskDefinition?.taskDefinitionArn!;
}
3️⃣ Spin up a Fargate service
async function createService(clusterArn: string, taskDefArn: string) {
const cmd = new CreateServiceCommand({
cluster: clusterArn,
serviceName: "cursor-tool-service",
taskDefinition: taskDefArn,
desiredCount: 1,
launchType: "FARGATE",
networkConfiguration: {
awsvpcConfiguration: {
subnets: ["subnet-0123456789abcdef0"], // replace with your subnet IDs
securityGroups: ["sg-0123456789abcdef0"], // SG that allows inbound 8080
assignPublicIp: "ENABLED", // for quick testing; use NAT in production
},
},
});
const resp = await ecs.send(cmd);
console.log(`✅ Service "${resp.service?.serviceName}" is up`);
}
Putting it together
async function deploy() {
const clusterArn = await createCluster("cursor-tool-cluster");
const taskDefArn = await registerTaskDef();
await createService(clusterArn, taskDefArn);
}
deploy().catch(err => console.error("❌ Deployment failed:", err));
What just happened?
-
createClustergave us a place to run tasks. -
registerTaskDeftold Fargate which Docker image to use and how much compute to allocate. -
createServicelaunched a task and kept one copy alive, exposing port 8080.
Tip: The
awslogsdriver automatically streams container logs to CloudWatch, making debugging much easier.
Table of required fields for the task definition
| Field | Meaning |
|---|---|
family |
Human‑readable name of the definition |
requiresCompatibilities |
Must include "FARGATE" to run on serverless infrastructure |
cpu / memory
|
Hard limits; pick values that match your expected load |
containerDefinitions |
List of containers (we have only one) |
portMappings |
Which container port should be reachable from the outside |
logConfiguration |
Where the container writes its stdout/stderr |
Connecting Cursor to Your ECS Endpoint
Cursor needs the URL of the /tool endpoint, plus an optional Authorization header if you protect the service. The editor reads these values from its settings file (cursor.json or the UI’s “Tools” section).
Example cursor.json snippet
{
"tools": [
{
"name": "ClaudeTool",
"url": "http://my-fargate-service-xyz.us-east-1.elb.amazonaws.com/tool",
"method": "POST",
"headers": {
"Authorization": "Bearer YOUR_JWT_HERE"
}
}
]
}
If your service lives behind an Application Load Balancer (ALB), use the ALB’s DNS name as the url. The ALB automatically forwards traffic to the Fargate task’s private IP.
In plain English: Tell Cursor where to knock, and it will hand over the request whenever it needs a tool.
Testing the connection locally
Before you point Cursor at the endpoint, you can verify the HTTP contract with curl:
curl -X POST https://my-fargate-service-xyz.us-east-1.elb.amazonaws.com/tool \
-H "Content-Type: application/json" \
-d '{"method":"runTests","params":{"path":"src"}}'
You should receive a JSON payload with a result field and a 200 status. If you see a 5xx error or the request hangs longer than 30 seconds, Cursor will give up.
Common Pitfalls and the 30‑Second Timeout Gotcha
Cursor’s built‑in retry logic only activates for HTTP 5xx (server‑side errors). It gives each tool call 30 seconds to finish, then aborts. Two mistakes happen often:
-
Returning
200with an error field – Cursor treats the response as success, discarding the error message silently. - Taking longer than 30 seconds – Cursor stops waiting, logs “tool timed out”, and does not retry because it thinks the request succeeded.
Correct response shape
// Inside your /tool handler after talking to Claude
const result = await callClaude(payload);
if (!result) {
// Real error: use 500 so Cursor retries
res.writeHead(500, { "Content-Type": "application/json" });
return res.end(JSON.stringify({ error: "Claude call failed" }));
}
// Success path – always 200 and a `result` key
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ result }));
Keeping the request fast
- Cache frequent Claude calls (e.g., using an in‑memory LRU cache).
- Parallelise independent sub‑tasks inside the handler.
- Set a lower Bedrock timeout (e.g., 10 seconds) and fall back to a cached answer if Bedrock exceeds that.
Tip: If you need more than 30 seconds for a specific tool, wrap the long work in an asynchronous job queue and have the tool return a job ID instead. Cursor can poll a second endpoint for status updates.
Example of a timeout‑safe handler
import { request } from "node:http";
/**
* Forward the incoming request to Bedrock's Claude model.
* The Bedrock SDK call is capped at 8 seconds.
*/
async function callClaude(payload: any) {
return new Promise((resolve, reject) => {
const timeout = setTimeout(() => reject(new Error("Bedrock timeout")), 8000);
// Fake Bedrock call – replace with real SDK call
setTimeout(() => {
clearTimeout(timeout);
resolve({ answer: `Echo: ${payload.method}` });
}, 2000); // simulate fast response
});
}
With the setTimeout guard, the handler will never exceed the 30‑second window, and any failure becomes a proper 5xx that Cursor will retry.
The Takeaway
Key points to remember
- Cursor’s Agent Mode is a lightweight HTTP contract; your tool server only needs to accept JSON, call Claude (or any other service), and reply with a
200payload. - Running the tool server on ECS Fargate gives you isolation, predictable resources, and the ability to scale without touching your laptop.
- The @aws-sdk/client-ecs package lets you script the whole lifecycle: cluster → task definition → service.
- Use an ALB or public IP so Cursor can reach the
/toolendpoint, and store the URL incursor.json. - Always return proper HTTP status codes. A
200with an error field looks like success to Cursor, while a5xxtriggers a retry. - Keep every tool call under 30 seconds; if you need longer work, off‑load it to a background job and return a job identifier instead.
Conclusion
By moving the Claude‑backed tool server into a Fargate task you free your editor from latency spikes, gain the ability to handle many simultaneous requests, and keep the deployment process fully code‑driven. The steps above—creating a cluster, registering a task definition, launching a service, and wiring Cursor to the endpoint—are all reproducible with a few lines of TypeScript. Remember the 30‑second timeout rule and use correct status codes, and you’ll see Cursor’s suggestions appear instantly, even when the underlying LLM work happens far away in the cloud. Happy coding!
Transparency notice
This article was written with the help of an AI system — Groq (GPT OSS 120B).
Published: 2026-11-17 · Primary focus: ECS
All code blocks are intended to be correct and runnable, but please verify them
against the official docs for the tools mentioned before using in production.Find an error? Drop a comment — corrections are always welcome.
Top comments (0)