Remote MCP (hosted)

POST https://win.oneshotagent.com/mcp (Streamable HTTP): wallet-minted token, credits, local MCP tools. Staging: https://api-stg.oneshotagent.com/mcp.

1. Mint an access token

First set budgets, then mint:

TypeScript (≥ 0.33.0)
Python (≥ 0.26.0)

import { OneShot } from '@oneshot-agent/sdk';

const agent = await OneShot.create({ cdp: true }); // or { privateKey }
const { token, id } = await agent.createAccessToken({ name: 'grok-bot' });
console.log(token); // oneshot_… — shown once, never stored server-side

from oneshot import OneShotClient

agent = OneShotClient("0x...")                       # wallet session
created = agent.create_access_token(name="grok-bot")
print(created["token"])                              # oneshot_… — shown once

# In the hosted environment (no wallet key):
hosted = OneShotClient.create(access_token=created["token"])  # resolves the address
hosted.call_tool("/v1/tools/search", {"query": "…"})           # billed to credits

Tokens spend agent credits under stored budgets. They cannot sign x402, change budgets or mint tokens. agent.revokeAccessToken(id) revokes; agent.listAccessTokens(): labels, last use, today’s spend. Python: snake case, plus a* async variants. Raw routes: POST/GET/DELETE /v1/agents/me/access-tokens, wallet-signed.

2. Add credits

From a wallet session; x402 pays the amount credited (Pricing).

TypeScript
Python
HTTP

const r = await agent.topUpCredits(25);   // pays $25 USDC, credits $25
console.log(r.credits_balance);          // "25.000000"

r = client.top_up_credits(25)
print(r["credits_balance"])

POST /v1/credits/top-up with { "amount": 25 } returns 402; sign and retry with payment-signature. Reference.

Token top-ups fail: 503 route_unavailable_for_access_tokens. Insufficient credits: isError: true:

{
  "error": "insufficient_credits",
  "message": "This call costs $0.010000 USDC but the credit balance is $0.002500 …",
  "required_usdc": "0.010000",
  "credits_balance": "0.002500",
  "shortfall_usdc": "0.007500"
}

The paid action did not proceed. Tool error insufficient_credits: top up before retrying. budget_exceeded: spending cap reached.

3. Connect a client

Settings → Apps & Connectors → Developer mode → Create: name OneShot, URL https://win.oneshotagent.com/mcp, OAuth. Sign in.

Settings → Connectors → Add custom connector: name OneShot, URL https://win.oneshotagent.com/mcp. Connect and sign in.

Connectors → New Connector → Custom: name OneShot, URL https://win.oneshotagent.com/mcp. Sign in; type @OneShot in chat.

.cursor/mcp.json, token from the environment:

{
  "mcpServers": {
    "oneshot": {
      "url": "https://win.oneshotagent.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ONESHOT_ACCESS_TOKEN}" }
    }
  }
}

claude mcp add --transport http oneshot https://win.oneshotagent.com/mcp \
  --header "Authorization: Bearer $ONESHOT_ACCESS_TOKEN"

Stateless Streamable HTTP with Accept: application/json, text/event-stream and Authorization: Bearer <token>.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://win.oneshotagent.com/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.ONESHOT_ACCESS_TOKEN}` } },
});
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);
const { tools } = await client.listTools();
const result = await client.callTool({ name: 'oneshot_web_search', arguments: { query: 'oneshot agent' } });

Connect with your OneShot account (OAuth)

OAuth clients use https://win.oneshotagent.com/mcp with no header; discovery at /.well-known/oauth-protected-resource/mcp. Sign in and choose an organization or your personal workspace; calls use its default agent and credits. Disconnect in account settings to stop spending; revoking the console token only rotates it next call. A new default agent has no sending domain: set from_domain to one you own, or request a new one (status: 'confirmation_required', quote_id, no charge). Repeat with confirm_new_domain: quote_id to register, charge exactly the quoted total and send. Wrong/expired quotes: no charge; omit the id for a fresh quote.

Budgets

PUT /v1/agents/me/budgets before hosted-token use (TypeScript SDK ≥ 0.54.0):

const agent = await OneShot.create({ cdp: true, budgets: { daily: 5 } });
// Construction stores nothing; config syncs before this wallet session's first paid call.
// Omit budgets to leave stored settings unchanged; no stored budget means unlimited.

// Wallet-signed: X-Agent-ID + x-agent-proof with scope "write".
await agent.route('PUT', '/v1/agents/me/budgets', { body: { daily: 5 } });
const stored = await agent.budgets();
if (stored.daily_usdc !== 5) throw new Error('Daily cap was not stored');

// Only after verification, hand this token to the hosted client.
const { token } = await agent.createAccessToken({ name: 'grok-bot' });

Credits count toward caps. At the cap, isError: true:

{ "error": "budget_exceeded", "reason": "daily", "cap": 5, "spent": 5, "charge": 0.01, "resets_at": "2026-09-09T00:00:00.000Z" }

Check status: agent.budgets() or oneshot_budget_status. Tokens cannot raise caps.

Funding compute goals

fundComputeGoal(goalId, amount), Python fund_compute_goal, MCP oneshot_compute_fund. Credits must cover the full amount; stored caps apply. Short of credits: top up from a wallet, or POST /v1/credits/checkout so a person pays by card.

Local server with a token

@oneshot-agent/mcp-server ≥ 0.20.0: ONESHOT_ACCESS_TOKEN replaces wallet credentials; credits only. Cannot combine with ONESHOT_BUDGET_*.

Troubleshooting

Symptom	Cause
`401` with `WWW-Authenticate: Bearer`	Missing, malformed, unknown, or revoked token.
`405`	POST only.
`406`	`Accept` lacks `application/json` or `text/event-stream`.
`429 too_many_attempts`	Repeated bad tokens from one IP lock that token prefix for 1 minute → 24 hours.
`no_sending_domain`	`oneshot_list_domains`, or set `from_domain`.
`budget_exceeded`	Raise it from a wallet session or wait for `resets_at`.

​1. Mint an access token

​2. Add credits

​3. Connect a client

​Connect with your OneShot account (OAuth)

​Budgets

​Funding compute goals

​Local server with a token

​Troubleshooting