[{"data":1,"prerenderedAt":606},["ShallowReactive",2],{"docs-en-\u002Fdocs\u002Fai\u002Fapi":3},{"id":4,"title":5,"body":6,"description":598,"extension":599,"meta":600,"navigation":601,"path":602,"seo":603,"stem":604,"__hash__":605},"docs_en\u002Fdocs\u002Fai\u002Fapi.md","Your own agents",{"type":7,"value":8,"toc":592},"minimark",[9,13,17,22,30,204,214,217,221,224,302,305,393,396,400,407,476,482,486,588],[10,11,5],"h1",{"id":12},"your-own-agents",[14,15,16],"p",{},"Both large model APIs can call a remote MCP server on your behalf. The key\ntravels with your request; Pelyr stores nothing beyond the usage counters it\nkeeps for every key.",[18,19,21],"h2",{"id":20},"claude-api","Claude API",[14,23,24,25,29],{},"The MCP connector needs ",[26,27,28],"strong",{},"both"," halves — the server, and a toolset that points\nat it by name — plus the beta header:",[31,32,37],"pre",{"className":33,"code":34,"language":35,"meta":36,"style":36},"language-bash shiki shiki-themes github-light github-dark","curl https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"anthropic-version: 2023-06-01\" \\\n  -H \"anthropic-beta: mcp-client-2025-11-20\" \\\n  -H \"content-type: application\u002Fjson\" \\\n  -d '{\n    \"model\": \"\u003Cyour model>\",\n    \"max_tokens\": 4096,\n    \"mcp_servers\": [\n      {\n        \"type\": \"url\",\n        \"name\": \"pelyr\",\n        \"url\": \"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\",\n        \"authorization_token\": \"pk_your_key_here\"\n      }\n    ],\n    \"tools\": [{ \"type\": \"mcp_toolset\", \"mcp_server_name\": \"pelyr\" }],\n    \"messages\": [\n      { \"role\": \"user\", \"content\": \"Which vessels are in the German Bight right now?\" }\n    ]\n  }'\n","bash","",[38,39,40,57,75,85,95,105,114,120,126,132,138,144,150,156,162,168,174,180,186,192,198],"code",{"__ignoreMap":36},[41,42,45,49,53],"span",{"class":43,"line":44},"line",1,[41,46,48],{"class":47},"sScJk","curl",[41,50,52],{"class":51},"sZZnC"," https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages",[41,54,56],{"class":55},"sj4cs"," \\\n",[41,58,60,63,66,70,73],{"class":43,"line":59},2,[41,61,62],{"class":55},"  -H",[41,64,65],{"class":51}," \"x-api-key: ",[41,67,69],{"class":68},"sVt8B","$ANTHROPIC_API_KEY",[41,71,72],{"class":51},"\"",[41,74,56],{"class":55},[41,76,78,80,83],{"class":43,"line":77},3,[41,79,62],{"class":55},[41,81,82],{"class":51}," \"anthropic-version: 2023-06-01\"",[41,84,56],{"class":55},[41,86,88,90,93],{"class":43,"line":87},4,[41,89,62],{"class":55},[41,91,92],{"class":51}," \"anthropic-beta: mcp-client-2025-11-20\"",[41,94,56],{"class":55},[41,96,98,100,103],{"class":43,"line":97},5,[41,99,62],{"class":55},[41,101,102],{"class":51}," \"content-type: application\u002Fjson\"",[41,104,56],{"class":55},[41,106,108,111],{"class":43,"line":107},6,[41,109,110],{"class":55},"  -d",[41,112,113],{"class":51}," '{\n",[41,115,117],{"class":43,"line":116},7,[41,118,119],{"class":51},"    \"model\": \"\u003Cyour model>\",\n",[41,121,123],{"class":43,"line":122},8,[41,124,125],{"class":51},"    \"max_tokens\": 4096,\n",[41,127,129],{"class":43,"line":128},9,[41,130,131],{"class":51},"    \"mcp_servers\": [\n",[41,133,135],{"class":43,"line":134},10,[41,136,137],{"class":51},"      {\n",[41,139,141],{"class":43,"line":140},11,[41,142,143],{"class":51},"        \"type\": \"url\",\n",[41,145,147],{"class":43,"line":146},12,[41,148,149],{"class":51},"        \"name\": \"pelyr\",\n",[41,151,153],{"class":43,"line":152},13,[41,154,155],{"class":51},"        \"url\": \"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\",\n",[41,157,159],{"class":43,"line":158},14,[41,160,161],{"class":51},"        \"authorization_token\": \"pk_your_key_here\"\n",[41,163,165],{"class":43,"line":164},15,[41,166,167],{"class":51},"      }\n",[41,169,171],{"class":43,"line":170},16,[41,172,173],{"class":51},"    ],\n",[41,175,177],{"class":43,"line":176},17,[41,178,179],{"class":51},"    \"tools\": [{ \"type\": \"mcp_toolset\", \"mcp_server_name\": \"pelyr\" }],\n",[41,181,183],{"class":43,"line":182},18,[41,184,185],{"class":51},"    \"messages\": [\n",[41,187,189],{"class":43,"line":188},19,[41,190,191],{"class":51},"      { \"role\": \"user\", \"content\": \"Which vessels are in the German Bight right now?\" }\n",[41,193,195],{"class":43,"line":194},20,[41,196,197],{"class":51},"    ]\n",[41,199,201],{"class":43,"line":200},21,[41,202,203],{"class":51},"  }'\n",[14,205,206,209,210,213],{},[38,207,208],{},"mcp_servers"," on its own is rejected as a validation error: the ",[38,211,212],{},"mcp_toolset","\nentry is what makes the tools visible to the model.",[14,215,216],{},"Field names and the beta header follow the provider's current documentation;\nthat documentation is the source of truth.",[18,218,220],{"id":219},"managed-agents","Managed agents",[14,222,223],{},"A managed agent declares the server without a token, and the token lives in a\nvault credential keyed by the server URL:",[31,225,229],{"className":226,"code":227,"language":228,"meta":36,"style":36},"language-json shiki shiki-themes github-light github-dark","{\n  \"display_name\": \"Pelyr OPEN-AIS\",\n  \"auth\": {\n    \"type\": \"static_bearer\",\n    \"mcp_server_url\": \"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\",\n    \"token\": \"pk_your_key_here\"\n  }\n}\n","json",[38,230,231,236,250,258,270,282,292,297],{"__ignoreMap":36},[41,232,233],{"class":43,"line":44},[41,234,235],{"class":68},"{\n",[41,237,238,241,244,247],{"class":43,"line":59},[41,239,240],{"class":55},"  \"display_name\"",[41,242,243],{"class":68},": ",[41,245,246],{"class":51},"\"Pelyr OPEN-AIS\"",[41,248,249],{"class":68},",\n",[41,251,252,255],{"class":43,"line":77},[41,253,254],{"class":55},"  \"auth\"",[41,256,257],{"class":68},": {\n",[41,259,260,263,265,268],{"class":43,"line":87},[41,261,262],{"class":55},"    \"type\"",[41,264,243],{"class":68},[41,266,267],{"class":51},"\"static_bearer\"",[41,269,249],{"class":68},[41,271,272,275,277,280],{"class":43,"line":97},[41,273,274],{"class":55},"    \"mcp_server_url\"",[41,276,243],{"class":68},[41,278,279],{"class":51},"\"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\"",[41,281,249],{"class":68},[41,283,284,287,289],{"class":43,"line":107},[41,285,286],{"class":55},"    \"token\"",[41,288,243],{"class":68},[41,290,291],{"class":51},"\"pk_your_key_here\"\n",[41,293,294],{"class":43,"line":116},[41,295,296],{"class":68},"  }\n",[41,298,299],{"class":43,"line":122},[41,300,301],{"class":68},"}\n",[14,303,304],{},"The agent itself only carries",[31,306,308],{"className":226,"code":307,"language":228,"meta":36,"style":36},"{\n  \"mcp_servers\": [\n    { \"type\": \"url\", \"name\": \"pelyr\", \"url\": \"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\" }\n  ],\n  \"tools\": [{ \"type\": \"mcp_toolset\", \"mcp_server_name\": \"pelyr\" }]\n}\n",[38,309,310,314,322,357,362,389],{"__ignoreMap":36},[41,311,312],{"class":43,"line":44},[41,313,235],{"class":68},[41,315,316,319],{"class":43,"line":59},[41,317,318],{"class":55},"  \"mcp_servers\"",[41,320,321],{"class":68},": [\n",[41,323,324,327,330,332,335,338,341,343,346,348,350,352,354],{"class":43,"line":77},[41,325,326],{"class":68},"    { ",[41,328,329],{"class":55},"\"type\"",[41,331,243],{"class":68},[41,333,334],{"class":51},"\"url\"",[41,336,337],{"class":68},", ",[41,339,340],{"class":55},"\"name\"",[41,342,243],{"class":68},[41,344,345],{"class":51},"\"pelyr\"",[41,347,337],{"class":68},[41,349,334],{"class":55},[41,351,243],{"class":68},[41,353,279],{"class":51},[41,355,356],{"class":68}," }\n",[41,358,359],{"class":43,"line":87},[41,360,361],{"class":68},"  ],\n",[41,363,364,367,370,372,374,377,379,382,384,386],{"class":43,"line":97},[41,365,366],{"class":55},"  \"tools\"",[41,368,369],{"class":68},": [{ ",[41,371,329],{"class":55},[41,373,243],{"class":68},[41,375,376],{"class":51},"\"mcp_toolset\"",[41,378,337],{"class":68},[41,380,381],{"class":55},"\"mcp_server_name\"",[41,383,243],{"class":68},[41,385,345],{"class":51},[41,387,388],{"class":68}," }]\n",[41,390,391],{"class":43,"line":107},[41,392,301],{"class":68},[14,394,395],{},"and the session attaches the vault. The key never reaches the agent's sandbox,\nwhich matters more here than elsewhere: a sandbox runs code the model wrote.",[18,397,399],{"id":398},"openai-responses-api","OpenAI Responses API",[14,401,402,403,406],{},"The Responses API takes the server as one entry in ",[38,404,405],{},"tools",":",[31,408,410],{"className":226,"code":409,"language":228,"meta":36,"style":36},"{\n  \"type\": \"mcp\",\n  \"server_label\": \"pelyr\",\n  \"server_url\": \"https:\u002F\u002Fapi.pelyr.com\u002Fmcp\",\n  \"authorization\": \"pk_your_key_here\",\n  \"require_approval\": \"never\"\n}\n",[38,411,412,416,428,439,450,462,472],{"__ignoreMap":36},[41,413,414],{"class":43,"line":44},[41,415,235],{"class":68},[41,417,418,421,423,426],{"class":43,"line":59},[41,419,420],{"class":55},"  \"type\"",[41,422,243],{"class":68},[41,424,425],{"class":51},"\"mcp\"",[41,427,249],{"class":68},[41,429,430,433,435,437],{"class":43,"line":77},[41,431,432],{"class":55},"  \"server_label\"",[41,434,243],{"class":68},[41,436,345],{"class":51},[41,438,249],{"class":68},[41,440,441,444,446,448],{"class":43,"line":87},[41,442,443],{"class":55},"  \"server_url\"",[41,445,243],{"class":68},[41,447,279],{"class":51},[41,449,249],{"class":68},[41,451,452,455,457,460],{"class":43,"line":97},[41,453,454],{"class":55},"  \"authorization\"",[41,456,243],{"class":68},[41,458,459],{"class":51},"\"pk_your_key_here\"",[41,461,249],{"class":68},[41,463,464,467,469],{"class":43,"line":107},[41,465,466],{"class":55},"  \"require_approval\"",[41,468,243],{"class":68},[41,470,471],{"class":51},"\"never\"\n",[41,473,474],{"class":43,"line":116},[41,475,301],{"class":68},[14,477,478,481],{},[38,479,480],{},"require_approval: \"never\""," is defensible here because every Pelyr tool is\nread-only and none of them spends anything but your own rate limit. Leave\napprovals on if your own policy says so.",[18,483,485],{"id":484},"what-to-expect","What to expect",[487,488,489,504,521,538],"ul",{},[490,491,492,495,496,499,500,503],"li",{},[26,493,494],{},"Tool errors are results, not transport failures."," Over the rate limit you\nget a tool result with ",[38,497,498],{},"error: \"rate_limited\""," and ",[38,501,502],{},"retry_after_seconds",", and\nthe connection stays authenticated. Same for a bad bounding box, an unknown\nMMSI, or a time range that reaches too far back.",[490,505,506,509,510,513,514,517,518,520],{},[26,507,508],{},"A revoked key is the exception."," It ends the connection: the next tool call\nreturns ",[38,511,512],{},"error: \"connection_invalid\""," or is refused with ",[38,515,516],{},"401",", every request\nafter that gets ",[38,519,516],{},", and the client has to sign in again or be given a new\nkey.",[490,522,523,534,535,537],{},[26,524,525,526,529,530,533],{},"An outage answers ",[38,527,528],{},"503"," with a ",[38,531,532],{},"Retry-After"," header",", never ",[38,536,516],{},". That\ndistinction is deliberate — a client must not read an outage as a revoked\nconnection and throw the credential away.",[490,539,540,543,544,337,547,337,550,337,553,249,556,337,559,337,562,565,566,569,570,573,574,577,578,499,581,584,585,587],{},[26,541,542],{},"Attribution travels in the answer."," Every tool result that carries vessel\ndata — ",[38,545,546],{},"find_vessels",[38,548,549],{},"get_vessel",[38,551,552],{},"get_vessel_track",[38,554,555],{},"vessels_at_time",[38,557,558],{},"search_vessels",[38,560,561],{},"get_detection_overflight",[38,563,564],{},"list_sts_finds"," —\ncarries an ",[38,567,568],{},"attribution"," block for the licences behind it; ",[38,571,572],{},"list_sources","\ncarries the same information per entry in its ",[38,575,576],{},"sources"," list instead.\n",[38,579,580],{},"list_detection_areas",[38,582,583],{},"list_detection_overflights"," carry no AIS vessel\nfacts, so their ",[38,586,568],{}," is empty.\nWhatever your agent shows or stores has to carry it too.",[589,590,591],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":36,"searchDepth":59,"depth":59,"links":593},[594,595,596,597],{"id":20,"depth":59,"text":21},{"id":219,"depth":59,"text":220},{"id":398,"depth":59,"text":399},{"id":484,"depth":59,"text":485},"Use the Pelyr MCP server from the Claude API, managed agents and the OpenAI Responses API.","md",{},true,"\u002Fdocs\u002Fai\u002Fapi",{"title":5,"description":598},"docs\u002Fai\u002Fapi","jA0rHwW-8mG_AfEE9wgCxZCFPGLB0Q1Itxc3xZFND0M",1793034560948]