AI Client Connection Guide (MCP)
How to connect an MCP-capable AI client to the AGENTIC STAR MCP endpoint. With the chat set, you ask an agent to do work; with the project set, you create and run projects, handle approval requests, and more. For the detailed specification of tools and scopes, see the MCP API Reference.
What You Need
- The AI client you use (Claude Code, Codex, Cursor, VS Code, or Claude)
- To connect as a person: an application (Client ID) created in the Console
- To connect as a system integration: a system integration created in the Console, and its API key
Install the Plugin (Recommended)
You can install the AGENTIC STAR plugin in Claude Code, Codex, and Claude. After installing it, ask "Connect to AGENTIC STAR", and it guides you through the connection.
| Included | What it does |
|---|---|
agenticstar-connect | Guides you through connecting to the AGENTIC STAR MCP endpoint |
agenticstar-projects | Creates projects, finds and fixes failures, handles approval requests, and reads results |
- The plugin does not include MCP connection settings. Set your Client ID or API key by following its guidance
- It is a different plugin from the Marketplace edition's. For the SaaS edition, use the plugin on this page
- Current version:
3.4.0
Download the plugin (agenticstar.zip)
- Claude Code
- Codex
- Claude
In the folder where you extracted the zip, run the following (Claude Code 2.1.292 or later).
claude plugin install agenticstar --marketplace ./agenticstar
In the folder where you extracted the zip, run the following.
codex plugin marketplace add ./agenticstar
codex plugin add agenticstar@agenticstar
Codex reads the plugin's instructions with the shell. Use it with the shell available.
In claude.ai or Claude Desktop, open Customize > Plugins, select Add > Upload plugin, and choose the zip as it is.
Choose How to Connect
| Who uses it | How to connect | What to prepare in the Console |
|---|---|---|
| A person (with their own account) | Sign in from the client | An application (Client ID) |
| A system (system integration) | Put a fixed API key in Authorization: Bearer | An API key of a system integration |
The MCP endpoint is shown below. Select the tool sets to use with toolsets (see Tool Sets).
https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project
The settings on this page are examples for reference. How to configure a client can change between its versions. For the latest instructions, see each client's documentation (Claude Code, Codex, Cursor, VS Code, Claude). For other MCP clients, set the endpoint, Client ID, and redirect URI by following that client's documentation.
Connect as a Person
1. Create an Application in the Console
Create it by following Console Guide — Steps to Create an Application.
- Application type: Select "Mobile / Native" (it has no Client Secret and signs in with PKCE)
- Redirect URI: Register the redirect URI of each client you use (see the table below)
- Scopes: Select
mcp:connectand the scopes of the tools you use. The scope for each tool is in MCP API Reference — Provided Tools (for example,chat:execfor the chat set,project:readto read projects)
| Client | Redirect URI to register |
|---|---|
| Claude Code | http://localhost:<port>/callback (the port you pass to --callback-port) |
| Codex | The value you set in callback_url (for example, http://localhost:<port>/callback) |
| Cursor (desktop app) | http://localhost:8787/callback |
| VS Code | http://127.0.0.1/ and https://vscode.dev/redirect |
| Claude | https://claude.ai/api/mcp/auth_callback |
- For redirect URIs on
http://127.0.0.1,http://[::1], orhttp://localhost, the port is not checked. If you register the URI without a port (for example,http://localhost/callback), you can sign in whatever port the client uses. If you register it with a port, only that port is accepted - For clients that let you choose the redirect URI (such as
callback_urlin Codex), we recommend127.0.0.1overlocalhost - If you registered
http://127.0.0.1:33418/for VS Code earlier, addhttp://127.0.0.1/to the client
2. Configure the Client and Sign In
Replace <client_id> with the Client ID of the application you created.
- Claude Code
- Codex
- Cursor
- VS Code
- Claude
claude mcp add --scope user --transport http \
--client-id <client_id> --callback-port <port> \
agenticstar 'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project'
Open /mcp in Claude Code and choose to authenticate agenticstar, or run claude mcp login agenticstar. The sign-in page opens in the browser.
Add the following to ~/.codex/config.toml.
[mcp_servers.agenticstar]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project"
[mcp_servers.agenticstar.oauth]
client_id = "<client_id>"
callback_port = <port>
callback_url = "http://localhost:<port>/callback"
Run codex mcp login agenticstar. The sign-in page opens in the browser.
Add the following to .cursor/mcp.json in your project (or ~/.cursor/mcp.json).
{
"mcpServers": {
"agenticstar": {
"url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project",
"auth": {
"CLIENT_ID": "<client_id>"
}
}
}
}
Enable agenticstar in the MCP list on the Customize page in the sidebar, and continue when asked to sign in. A server written in the project's .cursor/mcp.json is available in chats started in that project.
Add the following to .vscode/mcp.json in your workspace.
{
"servers": {
"agenticstar": {
"type": "http",
"url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project",
"oauth": {
"clientId": "<client_id>"
}
}
}
}
Start the server from "MCP: List Servers" in the Command Palette. The sign-in page opens in the browser.
- To use the tools from chat, VS Code chat (GitHub Copilot) must be available
- Set Session Target in the chat input to Local. Other harnesses (such as Copilot) do not receive this configuration and cannot connect
- If an earlier sign-in remains, sign out from your VS Code account before trying again
- Open the screen for adding a custom connector
- Free, Pro, and Max plans: open Customize > Connectors, select + Add, then Add custom connector (the Free plan allows one custom connector)
- Team and Enterprise plans: an Owner opens Organization settings > Connectors, selects Add, then Custom (Web)
- Enter a name and the endpoint URL above (with
?toolsets=chat,project), then select Continue - On the next screen, check that OAuth client is set to Use your own OAuth client, and enter the Client ID (leave the secret blank). For AGENTIC STAR, Authentication and OAuth client are selected automatically. Select Add
- On Free, Pro, and Max plans, select Connect and sign in to AGENTIC STAR in the browser that opens. On Team and Enterprise plans, after the Owner adds it, each member opens Customize > Connectors, selects the connector with the Custom label, clicks Connect, and signs in with their own account
By default, Claude asks for confirmation each time it uses a tool (deny, always allow, or allow once).
Claude connects to AGENTIC STAR from Anthropic's servers, not from the user's computer. The same connector works in claude.ai, Claude Desktop, and Cowork.
Connect as a System Integration
- Create it by following Console Guide — System Integration Creation Steps. Select
mcp:connectand, depending on the operations you use,project:readandproject:run, and set the project restriction - Issue an API key on the system integration's detail page (see Console Guide — API Key)
- Set
Authorization: Bearer <API key>in the client. You don't need to get a new token
- Claude Code
- Codex
- Cursor
- VS Code
claude mcp add --scope user --transport http agenticstar-system \
'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project' \
--header "Authorization: Bearer <API key>"
Put the API key in the environment variable AGENTICSTAR_API_KEY, and add the following to ~/.codex/config.toml.
[mcp_servers.agenticstar-system]
url = "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project"
bearer_token_env_var = "AGENTICSTAR_API_KEY"
{
"mcpServers": {
"agenticstar-system": {
"url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
"headers": {
"Authorization": "Bearer <API key>"
}
}
}
}
{
"inputs": [
{ "type": "promptString", "id": "agenticstar-api-key", "description": "AGENTIC STAR API key", "password": true }
],
"servers": {
"agenticstar-system": {
"type": "http",
"url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project",
"headers": {
"Authorization": "Bearer ${input:agenticstar-api-key}"
}
}
}
}
Set Session Target in the chat input to Local. Servers that use ${input:…} are not passed to other harnesses (such as Copilot).
A system integration can use the five operations of the project set (list of project_read, get of run_read, and start_run, fire_trigger, and cancel_run of project_run) and list_personas of the chat set (use toolsets=chat,project for list_personas). It can only work with projects within its project restriction. Claude has no way to connect as a system integration.
Use It Safely
- Operations that write: When you let the AI create, change, or delete projects, or decide approval requests, use the client's permission settings so that you can check each operation before it runs (Claude Code asks for permission every time before it decides an approval request. Claude lets you set permissions per tool. For other clients, see the client's documentation)
- Read-only use: For read-only use, create an application whose scopes are only
mcp:connectandproject:read - API key: Treat an API key as a secret, the same as a Client Secret. Don't paste it into chats or documents
- If credentials leak: When people connect, delete the application in the Console. For a system integration, delete the API key or disable the system integration. It can take up to about 1 minute to take effect (see Console Guide — If Credentials Leak)
Troubleshooting
- Tool sets: Without
toolsets, only the chat set is available. Specifyprojectto use the project set - Redirect URI mismatch: If the sign-in page shows a redirect URI error, check that the client's redirect URI matches the one registered in the Console (for Claude Code and Codex, the port)
- Missing scopes: When you call a tool without the required scope, a tool error returns the scope needed and what to do next. For a person's application, add the scope in the Console and sign in again
- System integration scope: A system integration can only work with projects within its project restriction
- Rejected for a system integration:
This endpoint is not available to client credentials(403) is returned when a system integration calls an operation it cannot use. To use that operation, connect as a person - Front-end protection (WAF): Depending on the input, a request can be stopped by the front-end protection. In that case the HTTP status is
403, and in the JSON bodyerror.codeiswaf_blocked. When there is a reference number, it is inerror.reference - When the tools change: When an AGENTIC STAR update changes the tools, reconnect (in Claude Code,
/mcp; in Claude, refresh the tool list from the connector's menu)
See Also
- MCP API Reference — Specification of tools, scopes, and errors
- Authentication Guide — Getting tokens and scopes
- Console Guide — Creating applications, system integrations, and API keys
- Connection Guide — Choosing between REST, MCP, and A2A