GoldenPi Bonds MCP Server

A Model Context Protocol server that exposes GoldenPi's reverse-engineered bond discovery APIs.

Tools:

• goldenpi_list_bonds — filtered, paginated bond listing via POST /v0/bonds/list
• goldenpi_search_bonds — free-text bond search via POST /v0/bonds/search

Installation

cd goldenpi-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Configuration

Copy .env.example to .env and edit as needed:

cp .env.example .env

Key variables:

Variable	Default	Purpose
GOLDENPI_BASE_URL	https://api.goldenpi.com	GoldenPi API base URL
GOLDENPI_CLIENT_TOKEN	(none)	Optional static token. If unset or rejected, the server falls back to /v0/auth/handshake.
GOLDENPI_PARTNER_ID	GoldenPi-Securities	Partner ID sent during handshake
GOLDENPI_SEND_DEPOSITORY_HEADER	0	Set to 1 to send x-gpi-client-depositoryid on POSTs. Off by default because the live API rejects it on bond endpoints.
GOLDENPI_MCP_TRANSPORT	sse	sse for ChatGPT apps / Render, stdio for OpenCode/Claude Desktop
GOLDENPI_MCP_HOST / GOLDENPI_MCP_PORT	0.0.0.0 / 8080	SSE server bind address. The standard PORT env var takes precedence over GOLDENPI_MCP_PORT.

Auth behavior:

1. Uses GOLDENPI_CLIENT_TOKEN if set.
2. If the static token fails with an auth/header error, automatically calls POST /v0/auth/handshake to obtain a guest token and retries.
3. If handshake also fails, the server exits immediately with a clear error.

Note: As of the latest test, the embedded static token from the frontend bundle is rejected by the live API. The handshake guest token works, so leaving GOLDENPI_CLIENT_TOKEN unset (or commented out) is the most reliable default.

Header note: The frontend only sends x-gpi-client-token on POST requests. Sending x-gpi-client-depositoryid on POST /v0/bonds/list causes an "invalid header" error, so this server does not send it by default. Set GOLDENPI_SEND_DEPOSITORY_HEADER=1 only if you specifically need it.

Running for ChatGPT / SSE clients (default)

python -m goldenpi_mcp.server

By default the server runs in SSE mode on 0.0.0.0:8080. Your ChatGPT app should connect to:

http://localhost:8080/sse

On Render, set the start command to python -m goldenpi_mcp.server and the server will automatically bind to the PORT env var Render provides.

Running locally (stdio / OpenCode / Claude Desktop)

python -m goldenpi_mcp.server --transport stdio

OpenCode / Claude Desktop config:

{
  "mcpServers": {
    "goldenpi-bonds": {
      "command": "python",
      "args": ["-m", "goldenpi_mcp.server", "--transport", "stdio"],
      "env": {
        "GOLDENPI_DEPOSITORY_ID": "GoldenPi"
      }
    }
  }
}

Tool reference

goldenpi_list_bonds

Filtered, paginated bond discovery via POST /v0/bonds/list. Does not support free-text search — use goldenpi_search_bonds for name/ISIN/issuer queries.

Pagination & sorting

Parameter	Type	Description
sort_by	enum	How to sort. Default: yield-high-to-low.
limit	int	Results per page. Range: 1–50. Default: 10.
offset	int	1-based page number. Default: 1.

Core filters

Parameter	Type	Description
asset_classes	list	Instrument types: NCD, NCD-IPO, GSEC, SDL, CGTB, SGB-IPO. Defaults to NCD, NCD-IPO.
credit_ratings	list	aaa, aa, a, sovereign. sovereign matches government securities.
min_yield / max_yield	number	YTMC % range. Omit either side for open-ended.
min_investment_inr / max_investment_inr	number	Settlement amount per lot in INR.
payment_frequencies	list	annual, half-yearly, quarterly, monthly, thrice-yearly, on-maturity.
issuer_types	list	nbfc, corporate, psu, psb, bank, government, gsec, sdl, rbi. gsec/sdl also enable government asset classes.
min_tenure_months / max_tenure_months	int	Remaining tenure in whole months. Ignored if tenure_preset is set.
tenure_preset	enum	Shortcut: less-than-1y, 1-5y, 5-10y, more-than-10y, short-term-3y.
investment_purpose	enum	Strategy preset applying multiple filters at once, e.g. highest-safety, tax-free-investment, invest-short-time.

Boolean flags

Parameter	Description
tax_free_only	Tax-free bonds only. Mutually exclusive with taxable_only.
taxable_only	Taxable bonds only.
nri_eligible_only	NRI-eligible bonds only.
secured_only / unsecured_only	Secured or unsecured only. Mutually exclusive.
perpetual_only / non_perpetual_only	Perpetual or non-perpetual only. Mutually exclusive.
call_option_only / no_call_option_only	With or without call option. Mutually exclusive.
pledge_for_fno_only	Accepted as pledge for F&O margin.
huf_tax_exemption_only	HUF tax exemption available.
spotlight_only	Featured/spotlight bonds only.

Advanced filters

Parameter	Type	Description
issuer_mode	enum	public (Public Placement) or private (Private Placement).
face_values	list	1000, 10000, 100000, 200000, 1000000, above-10-lacs. Combined into a range.
bond_price_level	enum	discount, par, premium.
bank_bond_tier	enum	tier_i, tier_ii, tier_iii.
seniority	enum	senior or subordinate.
depository_listing	enum	nsdl, cdsl, both.
listed	list	Override listing filter. [1] = active deals, [0] = primary/IPO, [0,1] = both.
include_marketing_details	bool	Include featured/UTSAV campaign metadata.

Output:

{
  "totalCount": 123,
  "filteredCount": 45,
  "hasMore": true,
  "bonds": [ /* full instList rows */ ]
}

goldenpi_search_bonds

Free-text search across bonds/FDs/IPOs via POST /v0/bonds/search.

Parameter	Required	Description
search_filter	yes	Name, ISIN, or issuer text. Minimum 2 characters.
sort_by	no	yield-high-to-low (default) or yield-low-to-high.
limit	no	Results per page. Range: 1–50. Default: 10.
offset	no	1-based page number. Default: 1.

Testing

pytest

Legal / risks

This is an unofficial reverse-engineered integration. GoldenPi may change their API without notice. Use at your own risk and respect their terms of service.