Skip to main content

Build a Cursor IDE Agent

Five integration options: from simple prompts to full MCP and TypeScript agents. All use OSSA/OAAS (agent.yml + openapi.yaml or manifest.ossa.yaml).

Try BuilderSpec

This guide shows five ways to bring OSSA/OAAS agents into Cursor. Each option uses the same dual-format contract: agent identity/capabilities (agent.yml or manifest.ossa.yaml) plus OpenAPI (openapi.yaml) for tools. Validation and golden template references apply to all.

Choose by complexity: Option 1 is fastest; Option 3 (MCP) is the most powerful for tools and resources.

Option 1: Cursor Built-in Prompts

Use Cursor's native prompt system to reference your agent

Add a prompt that loads your agent definition and instructs the model to follow it. Put your agent YAML in the repo (e.g. .agents/agent.yml or manifest.ossa.yaml) and reference it from Cursor prompts.

.cursor/prompts.json
json
{
  "prompts": [
    {
      "name": "Use project agent",
      "prompt": "Read and follow the agent definition in .agents/agent.yml (or manifest.ossa.yaml). Use the described capabilities and tools. Validate any tool calls against the OpenAPI spec in openapi.yaml."
    }
  ]
}

Option 2: VS Code Extension (TypeScript)

Validate agent + OpenAPI, file watcher, code actions

A small VS Code extension that: (1) Validates agent.yml / manifest.ossa.yaml and openapi.yaml. (2) Watches for file changes and re-validates. (3) Code action: "Validate OAAS/OSSA agent".

src/extension.ts (snippet)
typescript
import * as vscode from 'vscode';
import { readFileSync } from 'fs';
import { join } from 'path';

// Validate agent definition (agent.yml or manifest.ossa.yaml)
function validateAgent(yamlPath: string): { valid: boolean; errors: string[] } {
  const content = readFileSync(yamlPath, 'utf-8');
  // Use your preferred YAML + schema validator (e.g. js-yaml + ajv)
  const errors: string[] = [];
  // ... validation logic ...
  return { valid: errors.length === 0, errors };
}

// Validate OpenAPI 3.x
function validateOpenAPI(openApiPath: string): { valid: boolean; errors: string[] } {
  const content = readFileSync(openApiPath, 'utf-8');
  // ... OpenAPI validator ...
  return { valid: true, errors: [] };
}

export function activate(context: vscode.ExtensionContext) {
  const validateCommand = vscode.commands.registerCommand(
    'oaas.validate',
    async () => {
      const agentPath = join(vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? '', '.agents/agent.yml');
      const openApiPath = join(vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? '', 'openapi.yaml');
      const agentResult = validateAgent(agentPath);
      const openApiResult = validateOpenAPI(openApiPath);
      if (agentResult.valid && openApiResult.valid) {
        vscode.window.showInformationMessage('OAAS/OSSA agent and OpenAPI are valid.');
      } else {
        vscode.window.showErrorMessage(
          [...agentResult.errors, ...openApiResult.errors].join('; ')
        );
      }
    }
  );
  context.subscriptions.push(validateCommand);

  // File watcher: re-validate on save
  const watcher = vscode.workspace.createFileSystemWatcher('**/{.agents/agent.yml,manifest.ossa.yaml,openapi.yaml}');
  watcher.onDidChange(() => validateAgentAndNotify());
  context.subscriptions.push(watcher);

  // Code action provider
  const codeActionProvider = vscode.languages.registerCodeActionsProvider(
    { pattern: '**/{agent.yml,manifest.ossa.yaml,openapi.yaml}' },
    {
      provideCodeActions(document, range) {
        return [{
          title: 'Validate OAAS/OSSA agent',
          command: 'oaas.validate',
        }];
      },
    }
  );
  context.subscriptions.push(codeActionProvider);
}

Option 3: MCP Server (Recommended for Tools)

Expose tools and resources; Cursor connects via MCP

Run an MCP server that implements your agent: list tools (from OpenAPI or manifest), list resources (e.g. agent definition, spec), and execute tools. Cursor connects to this server via .cursor/mcp_config.json. This is the most powerful option for real tool use inside Cursor.

mcp-server.ts (conceptual)
typescript
import { McpServer } from '@modelcontextprotocol/sdk/server';
import { listTools, callTool } from './tools';   // from openapi.yaml
import { listResources, readResource } from './resources'; // agent.yml, openapi.yaml

const server = new McpServer({
  name: 'my-oaas-agent',
  version: '1.0.0',
});

server.setRequestHandler('tools/list', listTools);
server.setRequestHandler('tools/call', callTool);
server.setRequestHandler('resources/list', listResources);
server.setRequestHandler('resources/read', readResource);

// Stdio transport for Cursor
server.connect(process.stdin, process.stdout);
.cursor/mcp_config.json
json
{
  "mcpServers": {
    "my-oaas-agent": {
      "command": "node",
      "args": ["path/to/mcp-server.js"],
      "env": { "AGENT_DIR": ".agents" }
    }
  }
}

Option 4: .cursorrules (Project Rules)

Tell Cursor how to behave using your agent contract

Add a .cursorrules (or project rules in Cursor) that reference your agent and OpenAPI. Cursor will use this to constrain behavior and tool usage.

.cursorrules
text
# Project agent (OAAS/OSSA)
- The canonical agent definition is in .agents/agent.yml (or manifest.ossa.yaml).
- Tool schemas and behavior must match openapi.yaml in this repo.
- Before suggesting a tool call, validate it against the OpenAPI spec.
- Prefer the agent's described capabilities and instructions when answering.

Option 5: Full Cursor Agent Implementation (TypeScript)

Generate, validate, and migrate agent definitions

Implement a small "Cursor agent" in TypeScript that: generates an agent from a template, validates agent + OpenAPI, and optionally migrates from an existing MCP config. Cursor can run this via a task or extension that shells out.

cursor-agent.ts
typescript
import { generateAgent } from './generate';
import { validateAgent } from './validate';
import { migrateFromMCP } from './migrate';

export async function runCursorAgent(op: 'generate' | 'validate' | 'migrate', options: Record<string, string>) {
  switch (op) {
    case 'generate':
      await generateAgent(options.template ?? 'golden', options.output ?? '.agents/');
      break;
    case 'validate':
      const result = await validateAgent(options.agent ?? '.agents/agent.yml', options.openapi ?? 'openapi.yaml');
      if (!result.valid) throw new Error(result.errors.join('; '));
      break;
    case 'migrate':
      await migrateFromMCP(options.mcpConfig ?? '.cursor/mcp_config.json', options.output ?? '.agents/');
      break;
    default:
      throw new Error(`Unknown op: ${op}`);
  }
}

Golden template: a single source-of-truth agent + OpenAPI template (e.g. in a shared repo or OSSA docs) that projects copy and customize. Validation uses the same schema as the builder so Cursor and the web builder stay in sync.

Installation and Next Steps

Quick reference

  1. Option 1: Create .cursor/prompts.json and add your agent YAML to the repo.
  2. Option 2: Create a VS Code extension with the validate command, file watcher, and code action; install in Cursor.
  3. Option 3: Implement the MCP server (tools + resources), then add .cursor/mcp_config.json pointing to it. Restart Cursor.
  4. Option 4: Add .cursorrules (or project rules) with the rules above.
  5. Option 5: Add the TypeScript runner and wire it to a Cursor task or extension command (e.g. "OAAS: Validate").

For maximum power (tools + resources inside Cursor), use Option 3 (MCP). For the least setup, use Option 1 or 4. All options assume your project (or workspace) has an agent definition and, if you use tools, an OpenAPI spec.

See Also