Skip to main content
GhostStack
Menu
Navigation

guides

MCP Integration with Cortex Agents

Cortex and Vault

GhostStack Cortex is an agent framework for building autonomous workflows. Cortex agents often need credentials to interact with external services: calling APIs, querying databases, deploying code. Vault’s MCP server provides Cortex agents with a structured way to request credentials, bounded by leases and recorded in the audit log.

This guide shows how to wire Vault into a Cortex agent so the agent can request credentials at runtime, rather than having credentials baked into its configuration.

Register the Vault MCP server

In your Cortex agent configuration, add the Vault MCP server:

import { CortexAgent } from '@ghoststack/cortex';

const agent = new CortexAgent({
  name: 'deploy-agent',
  mcpServers: {
    vault: {
      command: 'npx',
      args: ['@ghoststack/vault-mcp', 'serve'],
      env: {
        VAULT_TOKEN: process.env.VAULT_TOKEN,
        VAULT_TENANT: 'my-org',
      },
    },
  },
});

The Cortex agent runtime starts the MCP server as a subprocess and makes its tools available to the agent.

Agent identity and attribution

When a Cortex agent requests a credential through the MCP server, the agent’s name is used as the identity in the lease:

{
  "identity": {
    "type": "agent",
    "name": "deploy-agent",
    "sessionId": "cortex_sess_abc123",
    "purpose": "Deploying v2.1.0 to production"
  }
}

The sessionId is generated by Cortex for each agent run. This lets you trace credential access back to a specific execution of a specific agent. If the same agent runs twice, each run gets its own session ID and its own audit trail.

Using credentials in agent tasks

A Cortex agent does not need to handle credential management explicitly. When the agent’s LLM decides it needs a credential, it calls the Vault MCP tool naturally:

const agent = new CortexAgent({
  name: 'api-integration-agent',
  systemPrompt: `You have access to Vault for credential management.
    When you need API keys or database credentials, request them
    through the vault_get_credential tool. Always declare why you
    need the credential.`,
  mcpServers: {
    vault: {
      command: 'npx',
      args: ['@ghoststack/vault-mcp', 'serve'],
      env: { VAULT_TOKEN: process.env.VAULT_TOKEN },
    },
  },
});

const result = await agent.run(
  'Fetch the latest orders from our Shopify store and summarize them.',
);

During this run, the agent will request the shopify-api-key credential from Vault, use it to call the Shopify API, and return the results. The credential lease expires after the configured TTL, and the entire interaction is logged.

Scoping agent permissions

Different agents should have access to different credentials. A deployment agent needs SSH keys and cloud credentials. An analytics agent needs database read-only URLs. A notification agent needs messaging API keys.

Create separate Vault tokens for each agent, scoped to only the credentials that agent needs:

// Deploy agent: access to deploy keys and cloud credentials
const deployAgent = new CortexAgent({
  name: 'deploy-agent',
  mcpServers: {
    vault: {
      command: 'npx',
      args: ['@ghoststack/vault-mcp', 'serve'],
      env: { VAULT_TOKEN: process.env.VAULT_TOKEN_DEPLOY },
    },
  },
});

// Analytics agent: access to read-only database credentials only
const analyticsAgent = new CortexAgent({
  name: 'analytics-agent',
  mcpServers: {
    vault: {
      command: 'npx',
      args: ['@ghoststack/vault-mcp', 'serve'],
      env: { VAULT_TOKEN: process.env.VAULT_TOKEN_ANALYTICS },
    },
  },
});

Lease management in long-running agents

Cortex agents can run for minutes or hours. For long-running tasks, configure the MCP server to renew leases automatically:

{
  "tenant": "my-org",
  "defaultTTL": "30m",
  "maxTTL": "4h",
  "autoRenew": true,
  "renewBeforeExpiry": "5m"
}

With autoRenew enabled, the MCP server renews active leases 5 minutes before they expire, up to the maxTTL limit. If the agent’s task exceeds the maxTTL, the lease cannot be renewed further and the agent must request a new lease.

Monitoring agent credential usage

The audit log supports filtering by agent name and session ID:

const logs = await vault.auditLog.query({
  filter: {
    'identity.name': 'deploy-agent',
    'identity.sessionId': 'cortex_sess_abc123',
  },
});

This returns every credential access for a specific agent run, making it straightforward to review what a particular execution did and which credentials it used.

Next steps