Agent Quickstart

Get an AI agent talking to your Upstox account in about five minutes. This guide wires up the hosted Upstox MCP server, points your agent at the full documentation set (including a machine-readable llms.txt), adds drop-in rules files so the agent follows Upstox conventions, and covers the guardrails that keep an autonomous agent safe.

Who this is for

This quickstart is for developers who want an AI coding agent or chat assistant — Claude, Claude Code, ChatGPT, Cursor, or VS Code with GitHub Copilot — to read from and reason about their Upstox account and the Upstox API.

You will get the most out of this guide if you:

• Build with an AI agent and want it grounded in accurate, up-to-date Upstox API knowledge.
• Want conversational, account-scoped access to holdings, orders, positions, and funds.
• Plan to automate research or trading workflows and need the agent to follow Upstox conventions.

If you only need programmatic API access without an AI agent, start with Authentication and the official SDKs instead.

Prerequisites

Before you begin, make sure you have:

• An active, non-dormant Upstox trading account. See Authentication to understand how OAuth links your account.
• One supported AI client: Claude Desktop or the Claude web app, Claude Code, ChatGPT with Developer mode, Cursor, or VS Code with GitHub Copilot.
• Node.js installed if your client connects over a local npx bridge. Claude Desktop and Claude Code connect natively and do not need Node.js.
• Basic familiarity with the Upstox API. The SDK guide is a good primer.

5-minute quickstart

Follow these three steps in order. Each one is expanded in its own section below.

Step 1 — Connect the MCP server

Add the hosted Upstox MCP server to your AI client so the agent can read your account data. This is the single most important step — see Connect the MCP server.

Step 2 — Feed the docs to your agent

Give the agent the Upstox documentation and the llms.txt index so it answers with accurate, current API knowledge instead of guessing. See Feed the docs to your agent.

Step 3 — Drop in rules files

Add rules files so the agent follows Upstox conventions and, if you use an agent skill, can execute trading workflows. See Drop-in rules files.

Connect the MCP server

The Upstox Model Context Protocol (MCP) server gives your AI assistant read-only access to your account data — holdings, orders, positions, mutual funds, funds, and profile — over a single hosted endpoint:

https://mcp.upstox.com/mcp

Most clients only need this URL. For example, a mcp-remote bridge configuration looks like this:

{
  "mcpServers": {
    "Upstox MCP": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.upstox.com/mcp"]
    }
  }
}

On first tool use the agent opens your browser for the Upstox OAuth consent, and you re-authorize once per day for security. Client-by-client setup — Claude Desktop, Claude Code, ChatGPT, Cursor, and VS Code — is covered in the MCP Integration guide.

Feed the docs to your agent

The MCP server exposes your account data, but the agent still needs to know how the Upstox API is shaped. Point it at the documentation so it writes correct requests and interprets responses accurately.

Two sources work well together:

• This documentation site — link the agent to the pages relevant to your task, such as Authentication and the SDK guide.
• The llms.txt index — a machine-readable map of the whole documentation set, published at pathname:///llms.txt. Fetch it once and hand it to your agent as context.

Fetch the llms.txt index

Download the index and pass it to your agent as a context file. The tab order is cURL, Python, Node.js, Java, PHP.

cURL

curl -s https://upstox.com/developer/api-documentation/llms.txt -o upstox-llms.txt

Python

import requests

url = "https://upstox.com/developer/api-documentation/llms.txt"
response = requests.get(url)
response.raise_for_status()

with open("upstox-llms.txt", "w", encoding="utf-8") as file:
    file.write(response.text)

Node.js

import { writeFile } from "node:fs/promises";

const url = "https://upstox.com/developer/api-documentation/llms.txt";
const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Failed to fetch llms.txt: ${response.status}`);
}

await writeFile("upstox-llms.txt", await response.text());

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://upstox.com/developer/api-documentation/llms.txt"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
Files.writeString(Path.of("upstox-llms.txt"), response.body());

PHP

<?php
$url = "https://upstox.com/developer/api-documentation/llms.txt";
$contents = file_get_contents($url);

if ($contents === false) {
    throw new RuntimeException("Failed to fetch llms.txt.");
}

file_put_contents("upstox-llms.txt", $contents);

With both the account data (via MCP) and the API knowledge (via the docs and llms.txt), the agent can answer grounded questions about your portfolio and generate correct API calls.

Drop-in rules files

Rules files tell your agent how to behave when it works with Upstox — which conventions to follow, which endpoints are read-only, and when to ask before acting. They keep an agent's output consistent across sessions and team members.

For agents that go beyond read-only analysis and actually place or manage orders, Upstox publishes a ready-made agent skill. See the Agent Skills guide to install the upstox-skill package, which ships a SKILL.md rules file and uses the official Upstox SDK to execute trades and stream data inside a coding agent.

Use the MCP server for read-only analysis and questions; add the agent skill when you want the agent to build and run trading workflows.

Safety & guardrails

An AI agent connected to a live trading account needs firm boundaries. Keep these guardrails in place:

• Read-only by default. The MCP server provides read-only access — the agent cannot place orders, modify positions, or move funds through it. Only the explicit agent skill can execute trades, so add it deliberately.
• Daily re-authorization. Account connections expire every day and require a fresh OAuth consent. This limits the window of any accidental or unauthorized access.
• Verify before acting. Treat AI output as research support, not investment advice. Cross-check important figures directly on the Upstox platform before you trade.
• Least privilege. Grant the agent only the access a task needs, and review the rules files so the agent asks for confirmation before any state-changing action.

Next steps

Now that your agent is connected, grounded, and guarded, go deeper:

• MCP Integration — full client-by-client setup, capabilities, and troubleshooting.
• Agent Skills — let a coding agent place and manage orders with the official SDK.
• Authentication — the OAuth flow behind the MCP connection.
• SDK guide — official libraries for building directly against the Upstox API.