Edgevana Compute Agent

Files for agents

• Agent Card: A2A Agent Card, JSON
• agents.md: This reference as Markdown
• llms.txt: Index of the files for language models
• API reference: The developer docs, for people
• API keys: Create an edgv_ key (sign-in)

Endpoints

Auth

X-API-Key: edgv_... or Authorization: Bearer edgv_...

API keys

https://nodes.edgevana.com/profile/api-keys (keys start with edgv_)

Transport

Streamable HTTP

Versions

MCP 2025-03-26 to 2025-11-25, A2A v0.3

Agent Card

Edgevana Edge AI Infrastructure, version 1.13.0, protocol 0.3.0

Approval before anything is charged

launch_instance, request_reserved_instance and terminate_instance run in two calls. The first call, without confirm, returns a preview and changes nothing. Show the preview to the user. Only after the user approves, send the same arguments again with confirm: true.

For launch_instance the preview returns the hourly price and an approval object, plus the deposit due today when the quote succeeds. The confirm call sends the approval object unchanged and a unique idempotency_key. If the offer was just taken, the preview may offer an equivalent one (same GPU, possibly another site) in substituted: show substituted.note, and confirm with substituted.offer_id and substituted.site. If the approved offer is taken by the time you confirm, an equivalent offer at the same site may be launched instead, never above the approved hourly price or deposit; a higher price is refused. The approved deposit is the ceiling. If approval.deposit_due_cents is null, run the preview again: a confirm without a deposit quote is refused.

request_reserved_instance sends a request to Edgevana sales: nothing is ordered or charged. terminate_instance destroys hourly GPU instances immediately, and that cannot be undone.

Tools (13)

These are the MCP names. A2A supports the same actions except request_reserved_instance; there, compare_to_cloud is compare_cloud and get_platform_info is platform_info.

{
  "name": "search_servers",
  "arguments": {
    "server_type": "gpu",
    "launchable_only": true,
    "max_price_hourly": 3,
    "min_vram_gb": 80,
    "limit": 5
  }
}

{
  "name": "get_server_specs",
  "arguments": {
    "sku": "<sku from search_servers>"
  }
}

{
  "name": "get_locations",
  "arguments": {
    "country": "United States"
  }
}

{
  "name": "check_availability",
  "arguments": {
    "server_type": "gpu",
    "site": "<site>",
    "limit": 10
  }
}

{
  "name": "get_pricing",
  "arguments": {
    "server_type": "gpu",
    "search": "H100",
    "include_locations": true
  }
}

{
  "name": "compare_to_cloud",
  "arguments": {
    "workload_type": "ai_training",
    "cloud_provider": "aws"
  }
}

{
  "name": "get_platform_info",
  "arguments": {
    "topic": "compute"
  }
}

{
  "name": "launch_instance",
  "arguments": {
    "offer_id": "<offer_id>",
    "site": "<one of its hourly_sites>",
    "ssh_key": "ssh-ed25519 AAAA…"
  }
}

{
  "name": "request_reserved_instance",
  "arguments": {
    "offer_id": "<offer_id>",
    "site": "<site>",
    "email": "[email protected]",
    "first_name": "Ada",
    "quantity": 8,
    "term_months": 12
  }
}

{
  "name": "list_instances",
  "arguments": {
    "limit": 20
  }
}

{
  "name": "get_instance",
  "arguments": {
    "instance_id": "<instance_id>"
  }
}

{
  "name": "update_instance",
  "arguments": {
    "instance_id": "<instance_id>",
    "custom_name": "training-01"
  }
}

{
  "name": "terminate_instance",
  "arguments": {
    "instance_id": "<instance_id>"
  }
}

Lifecycle (5 steps)

Values in angle brackets come from earlier calls; the approved object is an example, send the one from your preview.

1. 1. Search

   Pick an offer with launch_status "available". Note its offer_id and one of its hourly_sites.

   {
     "name": "search_servers",
     "arguments": {
       "server_type": "gpu",
       "query": "H100",
       "launchable_only": true,
       "sort": "price"
     }
   }

2. 2. Preview launch

   Returns the hourly price and an approval object, plus the deposit due today when the quote succeeds. Nothing is created. Show it to the user. If the deposit could not be quoted (approval.deposit_due_cents is null), run the preview again: a confirm without a deposit quote is refused.

   {
     "name": "launch_instance",
     "arguments": {
       "offer_id": "<offer_id>",
       "site": "<one of the offer’s hourly_sites>",
       "ssh_key": "ssh-ed25519 AAAA..."
     }
   }

3. 3. Confirm launch

   After the user approves: same args (or the substituted offer_id and site), confirm: true, the approval object unchanged, and a unique idempotency_key. If the approved offer is taken by the time you confirm, an equivalent offer at the same site may be launched instead, never above the approved hourly price or deposit; a higher price is refused.

   {
     "name": "launch_instance",
     "arguments": {
       "offer_id": "<offer_id>",
       "site": "<one of the offer’s hourly_sites>",
       "ssh_key": "ssh-ed25519 AAAA...",
       "confirm": true,
       "approved": {
         "hourly_cents": 89,
         "deposit_due_cents": 2500
       },
       "idempotency_key": "00000000-0000-4000-8000-000000000001"
     }
   }

4. 4. Monitor

   Check connection.status: ready, provisioning, failed, destroying or destroyed. destroying means the instance is cancelled but not yet confirmed gone. When ready, connection.ports lists mapped ports. connection.public_ip and connection.ssh can be null even when ready. Check connection.ssh before you read its host, port and user. When status is not ready, public_ip and ssh are null, and ports is [].

   {
     "name": "get_instance",
     "arguments": {
       "instance_id": "<instance_id>"
     }
   }

5. 5. Destroy

   Call without confirm for a preview, then again with confirm: true. Hourly GPU instances are destroyed immediately; EndOfTerm is refused for them.

   {
     "name": "terminate_instance",
     "arguments": {
       "instance_id": "<instance_id>",
       "confirm": true
     }
   }

A completed retry with the same idempotency_key and arguments returns the first result while the server keeps its record. That record resets when the server restarts. After an interrupted or failed launch, check list_instances before you retry.

Offers

GPU offer summaries returned by search_servers include launch_status and launch_note:

available

launch with launch_instance

coming_soon

not open for instant launch yet

request

reserved offer; send a no-charge request with request_reserved_instance over MCP

sold_out

no stock right now

Billing and deposits

Hourly GPU takes a non-refundable deposit when the instance is created. The amount depends on the hourly price, and the launch preview shows it (deposit.due_today). Credit already on the account counts towards it, and the deposit comes back as account credit against usage. Without an ssh_key the instance is billed but not provisioned.

Inbound ports and the connection object

launch_instance takes optional ports, such as ["7946/tcp", "7946/udp"]: up to 16, from 1 to 65535, not 22 (SSH is always mapped). The preview lists the normalized ports. The instance is ready only after every port is mapped.

A host that cannot map them fails with ERROR_PORTS_UNMAPPED after the port checks time out, and the service tries to destroy the instance. ERROR_PORTS_UNMAPPED does not confirm destruction. Check the instance (connection.status) before another launch. No hourly usage is billed before the instance is ready; the deposit stays as account credit.

Only hosts with direct ports can map ports, and SSH takes one of them: GPU offers report host.direct_port_count and host.reliability, so for N ports search with min_direct_ports N + 1 (and min_reliability, for example 0.99). The launch is refused before any spend when the host is known to have too few direct ports.

get_instance and list_instances return a connection object for each instance:

{
  "status": "ready",
  "public_ip": "203.0.113.7",
  "ssh": {
    "host": "203.0.113.7",
    "port": 40022,
    "user": "root"
  },
  "ports": [
    {
      "internal": 7946,
      "proto": "tcp",
      "external": 41234,
      "ip": "203.0.113.7"
    }
  ],
  "destroyed_at": null
}

destroyed_at is the confirmed destroy time after a cancel. It is null before that, after a failed launch is cleaned up, or when the time is unknown, and servers before 1.10.0 omit it. subscription.cancelled_at is the billing term start, not the destroy time.

Startup script (onstart)

launch_instance takes an optional onstart: a shell script of at most 4096 bytes (UTF-8, no NUL) that runs as root when the instance starts, and again on every restart, so make it safe to run twice. Instances run ubuntu:22.04 with the NVIDIA driver, and no CUDA libraries or Python; install what the workload needs in the script, and start long-running services in the background (setsid or nohup). The script is stored in plain text with the order: never put secrets in it. The preview and instance responses show only its bytes and sha256. The instance is ready when SSH accepts connections, not when the script finishes, so have the script delete a marker file first, write it as its last step, and check for it.

Limits

Results per call

search_servers and get_pricing: limit up to 50, default 20. check_availability: default 30.

Inbound ports

Up to 16 per instance, from 1 to 65535, not 22.

Startup script

onstart: at most 4096 bytes, UTF-8, no NUL.

Root disk

disk_gb within the offer’s disk_options, set at launch only; it cannot be resized later.

Idempotency key

8 to 128 characters, unique per launch.

Deposit

Set by the hourly price; the launch preview shows the amount.

Request rate limits

Not published.

Connect

claude mcp add --transport http edgevana https://mcp.edgevana.com/mcp --header "X-API-Key: YOUR_EDGV_KEY"

[mcp_servers.edgevana]
url = "https://mcp.edgevana.com/mcp"
env_http_headers = { "X-API-Key" = "EDGEVANA_API_KEY" }

{
  "mcpServers": {
    "edgevana": {
      "url": "https://mcp.edgevana.com/mcp",
      "headers": {
        "X-API-Key": "<your-edgv_...-key>"
      }
    }
  }
}

{
  "mcpServers": {
    "edgevana": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "https://mcp.edgevana.com/mcp",
        "--header",
        "X-API-Key:${EDGEVANA_API_KEY}"
      ],
      "env": {
        "EDGEVANA_API_KEY": "<your-edgv_...-key>"
      }
    }
  }
}

curl -X POST https://mcp.edgevana.com/a2a/jsonrpc \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_EDGV_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"message/send","id":1,"params":{"message":{"kind":"message","messageId":"msg-1","role":"user","parts":[{"kind":"text","text":"Find GPU servers"}]}}}'

curl https://edgevana.com/.well-known/agent-card.json

A command-line tool is coming soon. Until then, connect over MCP or A2A as above.