# Connect YouGile to an AI agent

MCP endpoint: https://ru.yougile.com/data/ai/mcp (Streamable HTTP). Server name: yougile.

YouGile manages projects, tasks, chats, CRM and knowledge bases. Tools act on behalf of the user within their permissions and the access granted to this connection.

## Agent workflow

1. Check whether this YouGile endpoint is already configured. Reuse a working connection; preserve other MCP servers and existing settings.
2. Find your client below. Prefer OAuth: add the server and start browser sign-in. The user signs in to YouGile, selects a company and grants access. Do not ask for their password or token in chat.
3. If you cannot change your own settings, explain the exact steps the user needs to take. If your client needs a restart or a new session to expose the tools, say so.
4. After sign-in, verify the connection with a live call to get_project_tree using {"id":null,"cursor":null,"projectState":"active"}. Read only the first page; do not create or change data to test the connection.
5. Report success only after a successful tool call. Briefly explain the available capabilities and any remaining sign-in or restart step.

## Codex

Add the server, then start browser sign-in:

```
codex mcp add yougile --url 'https://ru.yougile.com/data/ai/mcp'
codex mcp login yougile
```

Codex CLI, the app and the IDE extension share ~/.codex/config.toml. If the tools do not appear in the current session, restart the app or extension and verify the connection in a new session.

Official documentation: https://developers.openai.com/codex/mcp

## Claude Code

Add a user-level server:

```
claude mcp add --transport http --scope user yougile 'https://ru.yougile.com/data/ai/mcp'
```

Open /mcp in Claude Code, select yougile and authenticate in the browser. Restart the session if needed.

Official documentation: https://code.claude.com/docs/en/mcp

## Cursor

Merge this server into ~/.cursor/mcp.json, preserving existing servers:

```
{
  "mcpServers": {
    "yougile": {
      "url": "https://ru.yougile.com/data/ai/mcp"
    }
  }
}
```

Enable yougile in the MCP settings and complete browser authentication. Restart Cursor if needed.

Official documentation: https://cursor.com/docs/mcp

## VS Code

Use the MCP: Add Server command, choose HTTP, enter the endpoint above and name the server yougile. Choose the user configuration for a personal connection. Start the server and complete browser authentication.

The server entry in the user MCP configuration has this format:

```
{
  "servers": {
    "yougile": {
      "type": "http",
      "url": "https://ru.yougile.com/data/ai/mcp"
    }
  }
}
```

Official documentation: https://code.visualstudio.com/docs/agent-customization/mcp-servers

## Claude.ai, Claude desktop and ChatGPT

The user adds a custom MCP connector in their client settings with URL https://ru.yougile.com/data/ai/mcp and OAuth authentication, then confirms access in YouGile. A web-chat agent cannot edit its own connector settings; guide the user instead.

Web clients must be able to reach the installation from the internet. A private company installation may only be reachable by local clients on the company network.

## Other clients

Configure a remote Streamable HTTP server using the endpoint above and OAuth. Follow the client documentation for its configuration format.

## Without OAuth

If the client does not support OAuth, ask the user to create a connection in YouGile: My profile → AI assistants (MCP) → Connect a client. The user chooses a company, access permissions and whether to allow tab access. The token is shown once.

Ask the user to store the token themselves in the client secret storage or the YOUGILE_MCP_TOKEN environment variable. Never ask them to paste it into chat or put it in project files. Send it as Authorization: Bearer <token> using the client environment-variable support.

For Codex, use this configuration instead of OAuth:

```
[mcp_servers.yougile]
url = "https://ru.yougile.com/data/ai/mcp"
bearer_token_env_var = "YOUGILE_MCP_TOKEN"
```

## Company, permissions and tab access

A connection works with the company selected when authorizing. Reading and writing follow both the user permissions and the granted connection scope. An administrator may restrict MCP access.

Standard tools work on the server even with no YouGile tab open. With Tab access enabled, standard tools that support tab execution run in an open tab of the selected company without server rate limits; other standard calls run on the server under its rate limits. The extra tools query_tasks, grep_company_entities, get_current_ui_state and open_task require Tab access and an open tab of that company. Without a tab, use search_tasks for task search. Do not require a tab just to set up or verify a standard connection.

Access can be paused and individual connections revoked in My profile → AI assistants (MCP).